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JSR 340: Java Servlet 3.1 
Specification (Java Servlet 3.1 规范 》 


This is a Chinese translation of Java Serviet 3.1 Specification, and also provides a lot of 
useful examples about Servlet 3.1 . 


The intended audience for this specification includes the following groups: 


e Web server and application server vendors that want to provide servlet engines that 
conform to this standard. 

e Authoring tool developers that want to support Web applications that conform to this 
specification 

e Experienced servlet authors who want to understand the underlying mechanisms of 
servlet technology. 


本 书 是 《Java Servlet 3.1 规范 》 的 中 文 翻 译 ， 同 时 提供 了 大 量 Servlet 3.1 实例 ， 帮 助 你 快速 
理解 Servlet 3.1 规范 。 至 今 为 止 ，Servlet 3.1 是 最 新 的 正式 版 本 ，Servlet 4.0 BEE M 


za 
本 规范 的 目标 读者 有 如 下 几 种 : 


e. Web 服务 器 和 应 用 服务 器 供应 商 ， 用 于 开发 符合 此 标准 的 servlet 引擎 。 
e. 工具 开发 者 ， 想 要 开发 符合 此 规范 的 Web 应 用 的 支持 工具 。 
e. 有 经 验 的 servlet 开发 者 ， 想 要 理解 servlet 技术 的 底层 机 制 。 


该 规范 不 是 servlet 开发 人 的 用 户 指南 ， 而且 也 并 不 打算 被 用 作 这 样 。 用 于 此 目的 参考 文献 可 
以 到 http://java.sun.com/products/servlet 查 找 。 


本 书 利用 业余 时 间 编 写 ， 由 于 时 间 紧 姿 ， 精 力 和 能 力 有 限 ， 书 中 未 免 有 丝 漏 和 错误 ， 望 读者 
能 够 热忱 答 正 ， 点 此 提问 。 如 有 兴趣 ， 也 可 以 参与 到 本 翻译 工作 中 来 :) 


另外 有 GitBook 的 版 本 方便 阅读 http://waylau.gitbooks.io/servlet-3-1-specification ° 
书 中 所 有 实例 ， 在 samples 目录 下 。 


从 目录 开始 阅读 吧 ! 


Contact 联系 作者 : 


e Blog:www.waylau.com 
e Gmail: waylau521@gmail.com 
e Weibo: waylau521 


Introduction 


e Twitter: waylau521 
e Github : waylau 


本 文档 是 Java™ Servlet 规范 ， 针 对 版 本 是 3.1。 本 文档 描述 了 Java Servlet API 的 标准 。 


本 规范 制定 的 目的 是 给 Java Servlet 一 个 完整 和 清晰 的 解释 。 如 果 有 仍 有 问题 ， 可 以 查阅 以 
下 资料 : 


。 一 个 参考 实现 (简称 RI) : 已 经 实现 并 提供 了 本 规范 的 行为 基准 。 该 参考 实现 没有 对 一 
个 详细 的 特性 实现 去 诠释 ， 其 他 实现 者 可 以 以 参考 实现 作为 原型 ， 以 此 原型 完成 规范 。 

© 一 个 兼容 性 测试 套件 (简称 CTS) : 用 来 验证 实现 是 否 兼 容 Java Servlet API 标准 需 
求 。 并 且 测 试 结果 为 分 析 一 个 实现 是 不 是 标准 实现 提供 了 一 个 规范 值 。 

. 如 果 需 要 进一步 洪 清 疑问 ， 可 以 咨询 Java Community Process(Java 社区 进程 ， 简 称 
JCP) 控制 下 的 Java Servlet API 工作 组 ， 他 们 是 问题 的 最 终 判 定 者 。 


非常 欢迎 建议 和 反馈 ， 这 些 信息 可 以 用 来 改善 未 来 版 本 。 


谁 应 该 读 此 规范 


本 规范 的 目标 读者 有 如 下 几 种 : 


e. Web 服务 器 和 应 用 服务 器 供应 商 ， 用 于 开发 符合 此 标准 的 servlet 引擎 。 
eo 工具 开发 者 ， 想 要 开发 符合 此 规范 的 Web 应 用 的 支持 工具 。 
e. 有 经 验 的 servlet 开发 者 ， 想 要 理解 servlet 技术 的 底层 机 制 。 


该 规范 不 是 servlet 开发 人 的 用 户 指南 ， 而 且 也 并 不 打算 被 用 作 这 样 。 用 于 此 目的 参考 文献 可 
以 到 http://java.sun.com/products/servlet 查 找 。 


API 规范 


定义 了 Java Servlet API 中 类 、 接 口 、 方 法 签名 的 完整 规范 ， 且 附带 的 Javadoc 文档 有 可 用 
的 在 线 版 。 


其 他 的 Java 平台 规范 


该 规范 参考 如 下 其 他 Java API 规范 : 


Java Platform, Enterprise Edition ("Java EE"), version 7 

e JavaServer Pages™ ("JSP™"), version 2.2 

e Java Naming and Directory Interface™ ("J.N.D.I."). 

e Context and Dependency Injection for the Java EE Platform 
e Managed Beans specification 


这 些 规范 可 以 在 Java Platform, Enterprise Edition 网 站 中 找 
到 : http://java.sun.com/javaee/ ° 


其 他 重要 参考 资料 以 下 Internet 规 范 提供 了 一 些 有 关 开 发 和 实现 Java Servlet API 和 标准 
servlet 引 擎 的 信息 : 


e RFC 1630 Uniform Resource Identifiers (URI) 

e RFC 1738 Uniform Resource Locators (URL) 

e RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax 

e RFC 1808 Relative Uniform Resource Locators 

e RFC 1945 Hypertext Transfer Protocol (HTTP/1.0) 

e RFC 2045 MIME Part One: Format of Internet Message Bodies 

e RFC 2046 MIME Part Two: Media Types 

e RFC 2047 MIME Part Three: Message Header Extensions for non-ASCII text 
e RFC 2048 MIME Part Four: Registration Procedures 

e RFC 2049 MIME Part Five: Conformance Criteria and Examples 
e RFC 2109 HTTP State Management Mechanism 

e RFC 2145 Use and Interpretation of HTTP Version Numbers 

e RFC 2324 Hypertext Coffee Pot Control Protocol (HTCPCP/1.0)1 
e RFC 2616 Hypertext Transfer Protocol (HTTP/1.1) 

e RFC 2617 HTTP Authentication: Basic and Digest Authentication 
e RFC 3986 Uniform Resource Identifier (URI): Generic Syntax 


RFC 在 线 版 本 请 访问 : http://wwww.ietf.org/rfc/ ° 
万 维 网 联盟 (http://www.w3.org/) 是 影响 本 规范 和 实现 的 HTTP 相关 来 源 信 息 的 权威 。 


可 扩展 的 标记 语言 (XML) : 用 于 此 规范 第 13 章 描述 的 部 署 描述 符 。 更 多 的 XML 信息 可 以 在 
以 下 网 站 找到 : 


http://java.sun.com/xml 


http://www.xml.org/ 


提供 反馈 


我 们 欢迎 大 家 提供 此 规范 的 任意 和 所 有 的 反馈 。 请 发 送 你 的 建议 到 users@servlet- 
spec.java.net 邮箱 ° 


( 译 者 注 : 对 本 翻译 有 任何 意见 ， 可 在 https://github.com/waylau/servlet-3.1- 
specification/issuesže =] » ) 


请 注意 ， 由 于 我 们 收 到 大 量 的 反馈 意见 ， 你 可 能 不 能 正常 收 到 来 自 工程 师 的 回复 。 尽 管 如 
此 ， 规 范 团队 会 阅读 、 评 估 、 和 存档 每 一 个 建议 。 


专家 组 成 员 


e Deepak Anupalli (Pramati Technologies) 
e Euigeun Chung (TmaxSoft, Inc) 

e Robert Goff (IBM) 

e Richard Hightower 

e Seth Hodgson (Adobe Systems Inc.) 

e Remy Maucherat (RedHat) 

e Minoru Nitta (Fujitsu Limited) 

e Ramesh PVK (Pramati Technnologies) 
e Alex Rojkov (Caucho Technologies) 

e Mark Thomas (VMware) 

e Gregory John Wilkins 

e Wenbo Zhu (Google Inc.) 


EVA 


Oracle 的 Bill Shannon 为 该 规范 提供 了 非常 宝贵 的 技术 投入 。Oracle 的 Ron Monzillo # 344 
动 了 一 些 建 议和 围绕 安全 方面 的 技术 讨论 。 


什么 是 Servlet 


serviet 是 基于 Java 的 Web 组 件 ， 由 容器 进行 管理 ， 来 生成 动态 内 容 。 像 其 他 基于 Java 的 
组 件 技术 一 样 ，servlet 也 是 基于 平台 无 关 的 Java 类 格式 ， 被 编译 为 平台 无 关 的 字 节 码 ， 可 以 
被 基于 Java 技术 的 Web 服务 器 动态 加 载 并 运行 。 容 器 (Container) ， 有 时 候 也 叫做 servlet 
引擎 ， 是 Web 服务 器 为 支持 servlet 功能 扩展 的 部 分 。 客 户 端 通过 servlet 容器 实现 的 
request/response paradigm (请 求 /应 答 模式 ) 与 Servlet 进行 交互 。 


vu 


什么 是 Servlet 容器 


Servlet Container (Servlet 容器 ) Æ Web 服务 器 或 者 应 用 服务 器 的 一 部 分 ， 用 于 提供 基于 
请 求 /响应 发 送 模式 的 网 络 服务 ， 解 码 基 于 MIME 的 请 求 ， 并 且 格 式 化 基于 MIME 的 响应 。 
Servlet 容器 同时 也 包含 和 管理 他 们 的 生命 周期 里 Servlet 。 


Servlet 容器 可 以 诅 入 到 宿主 的 Web 服务 器 中 ， 或 者 通过 Web 服务 器 的 本 地 扩展 API 单独 作 
为 附加 组 件 安装 。Servelt FSA TANKA ZK ZLE A Web 功能 的 应 用 服务 器 中 。 


所 有 的 Servlet 容器 必须 支持 HTTP 协议 用 于 请 求 和 响应 ， 但 额外 的 基于 请 求 /响应 的 协议 ， 
如 HTTPS (HTTP over SSL) 的 支持 是 可 选 的 。 对 于 HTTP 规范 需要 版 本 ， 容 器 必须 支持 
HTTP/1.0 和 HTTP/1.1。 因为 容器 或 许 支持 RFC2616 (HTTP/1.1) 描 述 的 缓存 机 制 ， 缓 存 机 制 

可 能 在 将 客户 端 请 求 交 给 Servlet 处 理 之 前 修改 它们 ， 也 可 能 在 将 Servlet 生成 的 响应 发 送 给 
客户 端 之 前 修改 它们 ， 或 者 可 能 根据 RFC2616 规范 直接 对 请 求 作 出 响应 而 不 交 给 Servlet 进 
行 处 理 。 


Servlet 容器 应 该 使 Servlet 执行 在 一 个 安全 限制 的 环境 中 。 在 Java 平台 标准 版 (J2SE, v.1.3 
或 更 高 ) 或 者 Java 平 台 企 业 版 (Java EE, v.1.3 或 更 高 ) 的 环境 下 ， 这 些 限制 应 该 被 放置 在 
Java 平台 定义 的 安全 许可 架构 中 。 上 比如， 高 端的 应 用 服务 器 为 了 保证 容器 的 其 他 组 件 不 受到 
负面 影响 可 能 会 限制 Thread 对 象 的 创建 。 


Java SE 7 是 构建 Servlet 容器 最 低 的 Java 平 台 版 本 。 


se a ac 


以 下 是 一 个 典型 的 事件 序列 : 


1. 
2. 


客户 端 (如 web 浏览 器 ) 要 访问 Web 服务 器 ， 并 发 送 一 个 HTTP HR; 

Web 服务 器 接收 到 请 求 并 且 交 给 servlet 容器 处 理 ，servlet 容器 可 以 运行 在 与 宿主 Web 
服务 器 同一 个 进程 中 ， 也 可 以 是 同一 主机 的 不 同 进程 ， 或 者 位 于 不 同 的 主机 的 Web 服务 
器 中 ， 对 请 求 进行 处 理 。 

servlet 容器 根据 servlet 配置 选择 相应 的 servlet， 并 调用 代表 请 求 和 响应 的 对 象 。 
servlet 通过 请 求 对 象 得 EE > HTTP POST 参数 和 其 他 有 关 数 据 可 能 作为 请 求 的 
一 部 分 随 请 求 一 起 发 送 过 来 。Servlet 执行 我 们 编写 的 任意 的 逻辑 ， 然 后 动态 产生 响应 内 
容 发 送 回 客户 端 。 发 送 数 据 到 客户 端 是 通过 响应 对 象 完成 的 。 

一 旦 Servlet 完成 请 求 的 处 理 ，servlet 容器 必须 确保 响应 正确 的 输出 ， 并 且 将 控制 权 还 给 
Ta = Web 服务 器 。 


Servlet 与 其 他 技术 的 对 比 


从 功能 上 看 ，servlet 位 于 Common Gateway Interface (公共 网 关 接 口 ， 简 称 CGI) 程序 和 私 
有 的 服务 器 扩展 如 Netscape Server API (NSAPI) 或 Apache Modules 这 两 者 之 间 。 


相对 于 其 他 服务 器 扩展 机 制 Servlet 有 如 下 优势 : 


e 它们 通常 比 CGI 脚本 更 快 ， 因 为 采用 不 同 的 处 理 模型 。 

。 它们 采用 标准 的 API 从 而 支持 更 多 的 Web 服务 器 。 

。 它们 拥有 Java 编程 语言 的 所 有 优势 ， 包 括 容 易 开 发 和 平台 无 关 。 
e. 它们 可 以 访问 Java 平台 提供 的 大 量 的 API ° 


5 Java EE 的 关系 


Java Servlet API 3.1 版 本 是 Java 平台 企业 版 7 版 本 必须 的 API © Servlet 容器 和 servlet 被 部 
署 到 平台 中 时 ， 为 了 能 在 Java EE 环境 中 执行 ， 必 须 满足 JavaEE 规范 中 描述 的 额外 的 一 些 
要 求 。 


5 Servlet 2.5 规范 的 兼容 性 


处 理 注解 


在 Servlet 2.5 中 , metadata-complete 只 影响 在 部 署 时 的 注释 扫描 。 web-fragments 的 概念 在 
servlet 2.5 并 不 存在 。 然 而 在 servlet 3.0 和 之 后 ,metadata-complete 影响 扫描 所 有 的 在 部 署 
时 指定 部 署 信 息 和 web-fragments 注释 。 注 释 的 版 本 的 描述 符 必 须 不 影响 你 扫描 在 一 个 web 
应 用 程序 。 除 非 metadata-complete 指定 ， 规 范 的 一 个 特定 版 本 的 实现 必须 扫描 所 有 配置 的 
支持 的 注解 。 


Servlet 接口 


Servlet 接口 是 Java Servlet API 的 核心 抽象 。 所 有 Servlet 类 必须 直接 或 间接 的 实现 该 接 
口 ， 或 者 更 通常 做 法 是 通过 继承 一 个 实现 了 该 接口 的 类 从 而 复 用 许多 共性 功能 。 目 前 有 
GenericServlet 和 HttpServlet 这 两 个 类 实现 了 Servlet 接口 。 大 多 数 情况 下 ， 开 发 者 只 需要 继 
承 HttpServlet 去 实现 自己 的 Servlet PPT ° 


请 求 处 理 方 法 


基础 的 Servlet 接口 定义 了 service 方法 用 于 处 理 客户 端的 请 求 。 当 有 请 求 到 达 时 ， 该 方法 由 
servlet 容器 路 由 到 一 个 servlet 实例 来 调用 。 


Web 应 用 的 并 发 请 求 处 理 通常 需要 Web 开发 人 员 去 设计 适合 多 线程 执行 的 Servlet， 从 而 保 
证 service 方法 能 在 一 个 特定 时 间 点 处 理 多 线程 并 发 执行 。 ( 译 者 注 : Servlet 默认 是 线程 不 
安全 的 ， 需 要 开发 人 员 处 理 多 线程 问题 ) 


通常 Web 容器 对 于 并 发 请 求 将 使 用 同一 个 servlet 处 理 ， 并 且 在 不 同 的 线程 中 并 发 执行 
service 方法 。 


基于 HTTP 规范 的 请 求 处 理 方 法 


HttpServlet 抽象 子 类 在 基本 的 Servlet 之 上 添加 了 些 协 议 相关 的 方法 ， 并 且 这 些 方法 能 根据 
HTTP 请 求 类 型 自动 的 由 HttpServlet 中 实现 的 service 方法 转发 到 相应 的 协议 相关 的 处 理 方 
法 上 。 这 些 方法 是 : 


e doGet 处 理 HTTP GET 请 求 

e doPost 处 理 HTTP POST 请 求 

e doPut 处 理 HTTP PUT 请 求 

e doDelete 处 理 HTTP DELETE 请 求 

e doHead 处 理 HTTP HEAD 请 求 

e doOptions 处 理 HTTP OPTIONS 请 求 
e doTrace 处 理 HTTP TRACE 请 求 


一 般 的 ， 开 发 基于 HTTP 的 servlet 时 , Servlet 开发 人 员 只 需 去 实现 doGet 和 doPost 请 求 处 
理 方 法 即 可 。 如 果 开 发 人 员 想 使 用 其 他 处 理 方法 ， 其 使 用 方式 跟 之 前 的 是 类 似 的 ， 即 HTTP 
编程 都 是 类 似 。 


附加 方法 


doPut 和 doDelete 方法 允许 Servlet 开发 人 员 让 支持 HTTP/1.1 的 客户 端 使 用 这 些 功能 。 
HttpServlet 中 的 doHead 方法 可 以 认为 是 doGet 方法 的 一 个 特殊 形式 ， 它 仅 返 回 由 doGet 方 
法 产生 的 header 信息 。doOptions 方法 返回 当前 serviet 支持 的 HTTP 方法 。doTrace 方法 
返回 的 响应 包含 TRACE 请 求 的 所 有 头 信 息 。 


有 条 件 GET 支 持 


HttpServlet 定义 了 用 于 支持 有 条 件 GET 操作 的 getLastModified 方法 。 所 谓 的 有 条 件 GET 
操作 是 指 客 户 端 通过 GET 请 求 获 取 资 源 时 ， 当 资源 自 第 一 次 获取 那个 时 间 点 发 生 更 改 后 才 再 
次 发 生 数 据 ， 否 则 将 使 用 客户 端 缓存 的 数据 。 在 一 些 适当 的 场合 ， 实 现 此 方法 可 以 更 有 效 的 
利用 网 络 资 源 ， 减少 不必 要 的 数据 发 送 。 


实例 数量 


注解 描述 的 (第 8 章 注解 和 可 插 拔 性 ) 或 者 在 Web 应 用 程序 的 部 署 描述 符 (第 14 章 SPE 
wie) 中 描述 的 servlet 声明 ， 控 制 着 servlet 容器 如 何 提供 servlet 实例 。 


对 于 未 托管 在 分 布 式 环境 中 (默认) 的 servlet 而 言 ，servlet 容器 对 于 每 一 个 Servlet 声明 必 
须 且 只 能 产生 一 个 实例 。 不 过 ， 如 果 Servlet 实 现 了 SingleThreadModel 接口 ，servlet 容器 可 
义 选 择 实例 化 多 个 实例 以 便 处 理 高 负荷 请 求 或 者 串 行 化 请 求 到 一 个 特定 实例 。 


如 果 servlet 以 分 布 式 方式 进行 部 署 ， 容 器 可 以 为 每 个 Java Virtual Machine (JVMTM) 的 每 个 
Servlet 声明 产生 一 个 实例 。 但 是 ， 如 果 在 分 布 式 环境 中 servlet 实现 了 SingleThreadModel 
接口 ， 此 时 容器 可 以 为 每 个 容器 的 JVM 实例 化 多 个 Servlet 实例 。 


关于 Single Thread Model 


SingleThreadModel 接口 的 作用 是 保证 一 个 特定 servlet 实例 的 service 方法 在 一 个 时 刻 仅 能 被 
一 个 线程 执行 ， 一 定 要 注意 ， 此 保证 仅 适用 于 每 一 个 servlet 实例 ， 因 此 容器 可 以 选择 池 化 这 
些 对 象 。 有 些 对 象 可 以 在 同一 时 刻 被 多 个 servlet 实例 访问 ， 如 HttpSession 实例 ， 可 以 在 一 
个 特定 的 时 间 对 多 个 Servlet 可 用 ， 包 括 那些 实现 了 SingleThreadModel 接口 的 Servlet ° 


建议 开发 人 员 采 取 其 他 手段 来 解决 这 些 问题 ,而 不 是 实现 这 个 接口 ,如 避免 使 用 实例 变量 或 同步 
的 代码 块 访 问 这 些 资 源 。SingleThreadModel 接口 已 经 在 本 版 本 规范 中 弃 用 。 


Servlet 生命 周期 


Servlet 是 按照 一 个 严格 定义 的 生命 周期 被 管理 ， 该 生命 周期 规定 了 seu 如 何 被 加 载 、 实 
例 化 、 初 始 化 、 处 理 客户 端 请 求 ， 以 及 何 时 结束 服务 。 该 声明 周期 可 以 通 
javax.servlet.Servlet 接口 中 的 init、service 和 destroy 这 些 API 来 表示 > Servlet 必须 直 
接 或 间接 的 实现 GenericServlet 或 HttpServlet 抽象 类 。 


加 载 和 实例 化 


Servlet 容器 负责 加 载 和 实例 化 Servlet。 加 载 和 实例 化 可 以 发 生 在 容器 启动 时 ， 或 者 延迟 初始 
eg 


当 Servlet 引擎 启动 后 ，servlet 容器 必须 定位 所 需要 的 Servlet 类 。Servlet 容器 使 用 普通 的 
Java 类 加 载 设 施加 载 Servlet 类 。 可 以 从 本 地 文件 系统 或 远程 文件 系统 或 者 其 他 网 络 服务 加 
载 。 


加 载 完 Servlet 类 后 ， 容 器 就 可 以 实例 化 它 并 使 用 了 。 


初始 化 


servlet 对 象 实例 化 后 ， 容 器 必须 初始 化 servlet 之 后 才能 处 理 客 户 端的 请 求 。 初 始 化 的 目的 是 
以 便 Servlet 能 读 取 持 久 化 配置 数据 ， 初 始 化 一 些 代价 高 的 资源 (比如 JDBCT™ API 连接 ) > 
或 者 执行 一 些 一 次 性 的 动作 。 容 器 通过 调用 Servlet 实例 的 init 方法 完成 初始 化 ，init 方法 定 
义 在 Servlet 接口 中 ， 并 且 提 供 一 个 唯一 的 ServletConfig 接口 实现 的 对 象 作为 参数 ， 该 对 象 
每 个 Servlet 实例 一 个 。 配 置 对 象 允 许 Servlet 访问 由 Web 应 用 配置 信息 提供 的 键 - 值 对 的 初 
始 化 参数 。 该 配置 对 象 也 提供 给 Servlet 去 访问 一 个 ServletContext 对 象 ，ServletContext 描 


t F Servlet 的 运行 时 环境 。 请 参考 第 4 章 “Servlet 上 下 文 ”获取 ServletContext 接口 的 更 多 信 
自 o 


wo 


初始 化 时 的 错误 条 件 


在 初始 化 阶段 ，servlet 实例 可 能 抛 出 UnavailableException 或 ServletException 异常 。 在 这 
种 情况 下 ，servlet 不 能 放置 到 活动 服务 中 ，servlet 容器 必须 释放 它 。 如 果 初 始 化 没有 成 功 ， 
destroy 方法 不 应 该 被 调用 。 


在 实例 初始 化 失败 后 容器 可 能 再 实例 化 和 初始 化 一 个 新 的 实例 。 此 规则 的 例外 是 ， 当 抛 出 的 
UnavailableException 表示 一 个 不 可 用 的 最 小 时 间 ， 容 器 在 创建 和 初始 化 一 个 新 的 servlet 实 
例 之 前 必须 等 待 一 段 时 间 。 


使 用 工具 时 的 注意 事项 


当 一 个 工具 加 载 并 内 省 某 个 Web 应 用 时 触发 的 静态 初始 化 ， 这 种 用 法 与 调用 init 初始 化 方法 
是 有 区 别 的 。 在 Servlet 的 init 方法 没 被 调用 ， 开 发 人 员 不 应 该 假定 其 处 于 活动 的 容器 环境 
内 。 上 比如 ， 当 某 个 Servlet 仅 有 静态 方法 被 调用 时 ， 不 应 该 与 数据 库 或 企业 级 

JavaBean (EJB) 容器 建立 连接 。 


请 求 处 理 


servlet 完成 初始 化 后 ，servlet 容器 就 可 以 使 用 它 处 理 客户 端 请 求 了 。 客 户 端 请 求 由 
ServletRequest 类 型 的 请 求 对 象 表示 。servlet 封装 响应 并 返回 给 请 求 的 客户 端 ， 该 响应 由 
ServletResponse 类 型 的 响应 对 象 表示 。 这 两 个 对 象 是 由 容器 通过 参数 传递 到 Servlet 接 口 的 
service 方 法 的 。 


ew 
TE 


在 HTTP 请 求 的 场景 下 ， 容 器 提供 的 请 求 和 响应 对 象 具体 类 型 分 别 是 HttpServletRequest 和 
HttpServletResponse。 需要 注意 的 是 ， 由 servlet 容器 初始 化 的 某 个 servlet 实例 在 服务 期 
闻 ， 可 以 在 其 生命 周期 中 不 处 理 任何 请 求 。 


多 线程 问题 


servlet 容器 可 以 并 发 的 发 送 多 个 请 求 到 servlet 的 service 方法 。 为 了 处 理 这 些 请 求 ，Servlet 
开发 者 必须 为 service 方法 的 多 线程 并 发 处 理 做 好 充足 的 准备 。 


一 个 替代 的 方案 是 开发 人 员 实 现 SingleThreadModel 接口 ， 由 容器 保证 一 个 service 方法 在 
同一 个 时 间 点 仅 被 一 个 请 求 线程 调用 ， 但 是 此 方案 是 不 推荐 的 。servlet 容器 可 以 通过 串 行 化 
访问 servlet 的 请 求 ， 或 者 维护 一 个 servlet 实例 池 完 成 该 需求 。 如 果 Web 应 用 中 的 servlet 被 
标注 为 分 布 式 的 ， 容 器 应 该 为 每 一 个 分 布 式 应 用 程序 的 JVM 维护 一 个 Servlet 实例 池 。 


CR a 接口 的 servlet > (22 € service 方法 (或 者 是 那些 
HttpServlet 中 通过 service 。 派 的 doGet、doPost 等 分 派 方 法 ) 是 通过 synchronized 关 
键 词 定义 的 ，servlet 容器 不 能 使 用 实例 池 方 案 ， 并 且 只 能 使 用 序列 化 请 求 进行 处 理 。 强 列 
荐 开发 人 员 不 要 去 同 se service 方法 (或 者 那些 由 service 分 派 的 方法 ) ， 因 为 这 将 严重 影 
性 能 。 


请 求 处 理 时 的 异常 


servlet 在 处 理 一 个 请 求 时 可 能 抛 出 ServletException 或 UnavailableException 异常 。 
SEE 表示 在 处 理 请 求 时 出 现 了 一 些 错误 ， 容 器 应 该 采取 适当 的 措施 清理 掉 这 个 请 


UnavailableException 表示 servlet 目前 无 法 处 理 请 求 ， 或 者 临时 性 的 或 者 永久 性 的 。 


如 果 UnavailableException 表示 的 是 一 个 永久 性 的 不 可 用 ，servlet 容器 必须 从 服务 中 移 除 这 
个 servlet， 调 用 它 的 destroy 方法 ， 并 释放 servlet 实例 。 所 有 被 容器 拒绝 的 请 求 ， 都 会 返回 
一 个 SC_NOT_FOUND (404) 响应 s 


如 果 UnavailableException 表示 的 是 一 个 临时 性 的 不 可 用 ， 容 器 可 以 选择 在 临时 不 可 用 的 这 
段 时 间 内 路 由 任何 请 求 到 Servlet。 所 以 在 这 段 时 间 内 被 容器 拒绝 的 请 求 ， 都 会 返回 一 个 
SC_SERVICE_UNAVAILABLE (503) 响应 状态 码 ， 且 同时 会 返回 一 个 Retry-After 头 指示 此 
servlet 什么 时 候 可 用 。 容 器 可 以 选择 忽略 永久 性 和 临时 性 不 可 用 的 区 别 ， 并 把 
UnavailableException 视 为 永久 性 的 ， 从 而 serviet 抛 出 UnavailableException 后 需要 把 它 从 
服务 中 移 除 。 


异步 处 理 


有 时 候 ，Filter 及 /或 Servlet 在 生成 响应 之 前 必须 等 待 一 些 资源 或 事件 以 便 完 成 请 求 处 理 。 比 
如 ，Servlet 在 进行 生成 一 个 响应 之 前 可 能 等 待 一 个 可 用 的 JDBC 连接 ， 或 者 一 个 远程 web 
服务 的 响应 ， 或 者 一 个 JMS 消息 ， 或 者 一 个 应 用 程序 事件 。 在 Servlet 中 等 待 是 一 个 低 效 的 
操作 ， 因 为 这 是 阻塞 操作 ， 从 而 白白 占用 一 个 线程 或 其 他 一 些 受 限 资 源 。 许 多 线程 为 了 等 待 
一 个 缓慢 的 资源 比如 数据 库 经 常 发 生 阻 塞 ， 可 能 引起 线程 饥饿 ， 且 降低 整个 Web 容器 的 服务 
质量 。 


引入 了 异步 处 理 请 求 的 能 力 ， 使 线程 可 以 返回 到 容器 ， 从 而 执行 更 多 的 任务 。 当 开始 异步 处 
理 请 求 时 ， 另 一 个 线程 或 回调 可 以 或 者 产生 响应 ， 或 者 调用 完成 (complete) 或 请 求 分 派 
(dispatch) ， 这 样 ， 它 可 以 在 容器 上 下 文 使 用 AsyncContext.dispatch 方法 运行 。 一 个 典型 
的 异步 处 理事 件 顺 序 是 : 


1. 请 求 被 接收 到 ， 通 过 一 系列 如 用 于 验证 的 等 标准 的 filter 之 后 被 传递 到 Servlet » 

2. servlet 处 理 请求 参 数 及 (或) 内 容 体 从 而 确定 请 求 的 类 型 。 

3. 该 servlet 发 出 请 求 去 获取 一 些 资源 或 数据 ， 例 如 ， 发 送 一 个 远程 Web 服务 请 求 或 加 入 一 
个 等 待 JDBC 连接 的 队列 。 

4. serviet 不 产生 响应 并 返回 。 

5. 过 了 一 段 时 间 后 ， 所 请 求 的 资源 变 为 可 用 ， 此 时 处 理 线程 继续 处 理事 件 ， 要 么 在 同一 
线程 ， 要 么 通过 AsyncContext 分 派 到 容器 中 的 一 个 资源 上 。 


Java 企业 版 的 功能 ， 如 第 15.2.2 节 ， 在 "Web 应 用 环境 "和 第 15.3.1 节 ， 在 "EJB 调用 的 安全 标识 
传播 "'， 仅 在 初始 化 请 求 的 线程 执行 ， 或 者 请 求 经 过 AsyncContext.dispatch 方法 被 分 派 到 容 
器 。Java 企业 版 的 功能 可 能 支持 由 AsyncContext.start(Runnable) 方法 使 用 其 他 线程 直接 操 
作 响 应 对 象 。 


第 八 章 描述 的 @WebServlet 和 @WebFilter 注解 有 一 个 属性 一 asyncSupported，boolean 
类 型 默认 值 为 false。 当 asyncSupported 设置 为 true， 应 用 通过 执行 startAsync ( 见 下 文 ) 
可 以 启动 一 个 单独 的 线程 中 进行 异步 处 理 ， 并 把 请 求 和 响应 的 引用 传递 给 这 个 线程 ， 然 后 退 
出 原始 线程 所 在 的 容器 。 这 意味 着 响应 将 遍历 (相反 的 顺序 ) ee A (或 过 
滤器 链 ) 。 直 到 AsyncContext 调用 complete (WFX) FAET ARRA | wR AHER 
在 容器 启动 的 分 派 之 前 执行 ， 且 调用 了 startAsync 并 返回 给 容器 ， 此 时 应 用 需 负 责 处 理 请 求 
和 响应 对 象 的 并 发 访问 。 


从 一 个 Servlet 分 派 时 ， 把 asyncSupported=true 设置 为 false ou 的 。 这 种 情况 下 ， 当 
servlet 的 service 方法 不 支持 异步 退出 时 ， 响 应 Ba ， 且 容器 负责 调用 AsyncContext 的 
complete， 以 便 所 有 感 兴趣 的 AsyncListener 得 到 触发 。 过 滤器 a 青 理 要 完成 的 异步 任务 持 
有 的 资源 的 一 种 机 制 ， 也 应 该 使 用 AsyncListener.onComplete 触发 的 结果 。 


从 一 个 同步 Servlet 分 派 到 另 一 个 异步 Servlet 是 非法 的 。 不 过 与 该 点 不 同 的 是 当 应 用 调用 
startAsync 时 将 抛 出 lllegalStateException。 这 将 允许 servlet 只 能 作为 同步 的 或 异步 的 
Servlet ° 


应 用 在 一 个 与 初始 请 求 所 用 的 不 同 的 线程 中 等 待 异步 任务 直到 可 以 直接 写 响 应 ， 这 个 线程 不 
知道 任何 过 Ma E A ee a 

包装 响应 ， 并 且 把 包装 的 响应 传递 给 链 中 的 下 一 个 过 滤器 ， 并 最 终 交 给 Servlet。 因 此 ， 如 果 
响应 是 包装 的 (可 能 被 包装 多 次 ， 每 一 个 过 滤器 一 次 ) ， 并 且 应 用 处 理 请 求 并 直接 写 响 应 ， 
这 将 只 写 响 应 的 包装 对 象 ， 即 任何 输出 的 响应 都 会 由 响应 的 包装 对 象 处 理 。 当 应 用 在 一 个 单 
独 的 线程 中 读 请 求 时 ， 写 内 容 到 响应 的 包装 对 象 ， 这 其 实 是 从 请 求 的 包装 对 象 读 取 ， 并 写 到 
响应 的 包装 对 象 ， 因 此 对 包装 对 象 操 作 的 所 有 输入 及 【或 ) 输出 将 继续 存在 。 


如 果 应 用 选择 这 样 做 的 话 ， 它 将 可 以 使 用 AsyncContext 从 一 个 新 线程 发 起 到 容器 资源 的 分 派 
请 求 。 这 将 允许 在 容器 范围 内 使 用 像 JSP 这 种 内 容 生 成 技术 。 


除了 注解 属性 外 ， 我 们 还 添加 了 如 下 方法 /类 : 


e ServietRequest 
o public AsyncContext startAsync(ServletRequest req, ServietResponse res)°。 这 个 
方法 的 作用 是 将 请 求 转 换 为 异步 模式 ， 并 使 用 给 定 的 请 求 及 响应 对 象 和 
getAsyncTimeout 返回 的 超时 时 间 初 始 化 它 的 AsyncContext。ServletRequest 和 
ServletResponse 参数 必须 是 与 传递 给 servlet 的 service A filter 的 doFilter 方 法 相 
同 的 对 象 ， 或 者 是 ServletRequestWrapper 和 ServletResponseWrapper 子 类 的 包装 
对 象 。 当 应 用 退出 service 方法 时 ， 调 用 该 方法 必须 确保 响应 没有 被 提交 。 当 调用 返 
回 的 AsyncContext 的 m complete 或 AsyncContext 超时 并 且 没有 监听 
器 处 理 超时 时 ， 它 将 被 提交 。 异 步 超时 定时 器 直到 请 求 和 它 关 联 的 响应 从 容器 返回 

时 才 启 动 。AsyncContext 可 以 被 异步 线程 用 来 写 响 应 ， 它 也 能 用 来 通知 没有 关闭 和 
提交 的 响应 。 


如 果 请 求 在 不 支持 异步 操作 的 servlet 或 filter 范 围 中 调用 startAsync， 或 者 响应 已 经 被 提交 或 关 
闭 ， 或 者 在 同一 个 分 派 期 间 重 复 调 用 ， 这 些 是 非法 的 。 从 调用 startAsync 返回 的 
AsyncContext 可 以 接着 被 用 来 进行 进一步 的 异步 处 理 。 调 用 返回 的 AsyncContext 的 
hasOriginalRequestResponse() 方法 将 返回 false， 除 非 传 过 oe 和 
ServletResponse 参数 是 最 原始 的 那个 或 不 是 应 用 提供 的 包装 器 


在 请 求 设置 为 异步 模式 后 ， 在 入 站 调用 期 间 添 加 的 一 些 请 求 及 (或 ) 响应 的 包装 器 可 能 需 
在 异步 操作 期 间 一 直 保 持 ， 并 且 它 们 关联 的 资源 可 能 也 不 会 释放 ， 出 站 方向 调用 的 所 有 过 滤 
器 可 以 以 此 作为 一 个 标志 。 一 个 在 入 站 调用 期 间 的 过 滤器 应 用 的 ServletRequestWrapper 可 


ce 出 站 调用 的 过 滤器 释放 ， 只 有 当 给 定 的 ServletRequest 是 由 AsyncContext 初始 化 的 且 


过 调用 AsyncContext.getRequest() 返回 的 ， 不 包括 之 前 说 的 ServletRequestWrapper。 这 


| 同样 适用 于 ServletResponseWrapper 实例 。 


public AsyncContext startAsync() 是 一 个 简便 方法 ， 使 用 原始 的 请 求 和 响应 对 象 用 于 蜡 
步 处 理 。 请 注意 ， 如 果 它 们 在 你 想 调用 此 方法 之 前 被 包装 了 ， 这 个 方法 的 使 用 者 应 该 刷 
E (flush) 响应 ， 确 保 数据 写 到 被 包装 的 响应 中 没有 丢失 。 

public AsyncContext getAsyncContext() — 返回 由 startAsync 调用 创建 的 或 初始 化 的 
AsyncContext。 如 果 请 求 已 经 被 设置 为 异步 模式 ， 调 用 getAsyncContext 是 非法 的 。 
public boolean = a go ni true > S miz E 
false。 一 旦 请 求 传 给 了 过 滤器 或 servlet 不 支持 异步 处 理 〈 通 定 的 注解 或 声明 ) HE 
步 支 持 将 被 禁用 。 

public boolean isAsyncStarted() — 如 果 请 求 的 异步 处 理 已 经 开始 将 返回 trtue， 否 则 返回 
false。 如 果 这 个 请 求 自从 被 设置 为 异步 模式 后 已 经 使 用 任意 一 个 AsyncContext.dispatch 
方法 分 派 ， 或 者 成 功 调用 了 AsynContext.complete 方法 ， 这 个 方法 将 返回 false 。 

public DispatcherType getDispatcherType() — 返回 请 es y IRB (dispatcher) 类 型 。 容 
器 使 用 请 求 的 分 派 器 类 型 来 选择 需要 应 用 到 请 求 的 过 滤器 。 只 有 匹配 分 派 器 类 型 和 url 模 
A (url pattern) 的 过 滤器 才 会 被 应 用 。 人 允许 一 个 过 滤器 配置 多 个 分 派 器 类 型 ， 过 滤器 可 
以 根据 请 求 的 不 同 分 派 器 类 型 处 理 请 求 。 请 求 的 初始 分 派 器 类 型 定义 为 
DispatcherType.REQUEST ° 14% Ħ RequestDispatcher.forward(ServletRequest, 
ServletResponse) 或 RequestDispatcher.include(ServletRequest, ServletResponse) 分 
派 时 ， 它 们 的 请 求 的 分 派 器 类 型 分 别 是 DispatcherType.FORWARD 或 
DispatcherType.INCLUDE ， 当 一 个 异步 请 求 使 用 任意 一 个 AsyncContext.dispatch 方法 
分 派 时 该 请 求 的 分 派 器 类 型 是 DispatcherType.ASYNC。 最 后 ， 由 容器 的 错误 处 理 机 制 分 
派 到 错误 页 面 的 分 派 器 类 型 是 DispatcherType.ERROR 。 

o AsyncContext - 该 类 表示 在 ServletRequest 启动 的 异步 操作 执行 上 下 文 ， 
AsyncContext 由 之 前 描述 的 ServletRequest.startAsync 创建 并 初始 化 。 
AsyncContext 的 方法 : 

public ServletRequest getRequest() — 返回 调用 startAsync 用 于 初始 化 AsyncContext 的 
请 求 对 象 。 当 在 异步 周期 之 前 调用 了 complete 或 任意 一 个 dispatch 方法 ， 调 用 
getRequest 将 抛 出 IllegalStateException ° 

public ServletResponse getResponse() -返回 调用 startAsync 用 于 初始 化 AsyncContext 
的 响应 对 象 。 当 在 异步 周期 之 前 调用 了 complete 或 任意 一 个 dispatch 方法 ， 调 用 
getResponse 将 抛 出 lllegalStateException。 

public void setTimeout(long timeoutMilliseconds) — 设置 异步 处 理 的 超时 时 间 ， 以 毫秒 为 
单位 。 该 方法 调用 将 履 盖 容器 设置 的 超时 时 间 。 如 果 没 有 调用 setTimeout 设置 超时 时 
间 ， 将 使 用 容器 默认 的 超时 时 间 。 一 个 小 ee A ed E 当 调 用 
任意 一 个 ServletRequest.startAsync 方法 时 ， 一 旦 容器 启动 的 分 派 返 回 到 容器 ， 超 时 时 
间 将 应 用 到 AsyncContext。 当 在 异步 周期 开始 时 容器 启动 的 分 派 已 经 返 as 容 SRE 再 
设置 超时 时 间 是 非法 的 ， 这 将 抛 出 一 个 jlegalStateException 异常 

public long getTimeout() — 获取 AsyncContext 关联 的 超时 时 间 的 毫秒 值 。 该 方法 返回 容 


器 默认 的 超时 时 间 ， 或 最 近 一 次 调用 setTimeout 设置 超时 时 间 。 

e public void addListener(AsyncListener listener, ServietRequest req, ServletResponse 
res) 一 注册 一 个 用 于 接收 的 onTimeout, onError, onComplete 或 onStartAsync 通知 的 监 
听 器 。 前 三 个 是 与 最 近 通 过 调用 任意 ServletRequest.startAsync 方法 启动 的 异步 周期 相 
关联 的 。onStartAsync 是 与 通过 任意 ServletRequest.startAsync 局 动 的 一 个 新 的 异步 周 
期 相关 联 的 。 异 步 监 听 器 将 以 它们 添加 到 请 求 时 的 顺序 得 到 通知 。 当 AsyncListener 得 到 
通知 ， 传 入 到 该 方法 的 请 求 响应 对 象 与 AsyncEvent.getSuppliedRequest() 和 
AsyncEvent.getSuppliedResponse() 是 完全 相同 的 。 不 应 该 对 这 些 对 象 进 行 读 取 或 写 
入 ， 因 为 自从 注册 了 AsyncListener 后 可 能 发 生 了 额外 的 包装 ， 不 过 可 以 被 用 来 按 顺 序 释 
放 与 它们 关联 的 资源 。 容 器 启动 的 分 派 在 异步 周期 启动 后 返回 到 容器 后 ， 或 者 在 一 个 新 
的 异步 周期 启动 之 前 ， 调 用 该 方法 是 非法 的 ， 将 抛 出 川 egalStateException 。 

e public createListener(Class clazz) 一 实例 化 指定 的 AsyncListener 类 。 返 回 的 
AsyncListener 实例 在 使 用 下 文 描述 的 addListener 方法 注册 到 AsyncContext 之 前 可 能 需 
要 进一步 的 自 定 义 。 给 定 的 AsyncListener 类 必须 定义 一 个 用 于 实例 化 的 空 参 构造 器 ， 该 
方法 支持 适用 于 AsyncListener 的 所 有 注解 。 

* public void addListener(AsyncListener) — 注册 给 定 的 监听 器 用 于 接收 onTimeout, 
onError onComplete 或 onStartAsync 通 知 。 前 三 个 是 与 最 近 通 过 调用 任意 
ServletRequest.startAsync 方 法 启动 的 异步 周期 相关 联 的 。onStartAsync 是 与 通过 任意 
ServletRequest.startAsync 启动 的 一 个 新 的 异步 周期 相关 联 的。 异步 监听 器 将 以 它们 添 
加 到 请 求 时 的 顺序 得 到 通知 。 当 AsyncListener 接收 到 通知 ， 如 果 在 请 求 时 调用 
startAsync(req, res) 或 startAsync()， 从 AsyncEvent 会 得 到 同样 的 请 求 和 响应 对 象 。 请 
求 和 响应 对 象 可 以 是 或 者 不 是 被 包装 的 。 异 步 监听 器 将 以 它们 添加 到 请 求 时 的 顺序 得 到 
通知 。 容 器 启动 的 分 派 在 异步 周期 启动 后 返回 到 容器 后 ， 或 者 在 一 个 新 的 异步 周期 启动 
之 前 ， 调 用 该 方法 是 非法 的 ， 将 抛 出 lllegalStateException 。 

e public void dispatch(String path) — 将 用 于 初始 化 AsyncContext 的 请 求 和 响应 分 派 到 指定 
的 路 径 的 资源 。 该 路 径 以 相对 于 初始 化 AsyncContext 的 ServletContext 进行 解析 。 与 请 
求 查 询 方 法 相关 的 所 有 路 径 ， 必 须 反 映 出 分 派 的 目标 ， 同 时 原始 请 求 的 URI， 上 下 文 ， 路 
径 信 息 和 查询 字符 串 都 可 以 从 请 求 属性 中 获取 ， 请 求 属性 定义 在 9.7.2 章 节 ，“ 分 派 的 请 求 
参数 "。 这 些 属 性 必须 反映 最 原始 的 路 径 元 素 ， 即 使 在 多 次 分 派 之 后 。 

e public void dispatch() — 一 个 简便 方法 ， 使 用 初始 化 AsyncContext 时 的 请 求 和 响应 进行 
分 派 ， 如 下 所 示 。 如 果 使 用 startAsync(ServletRequest, ServietResponse) 初始 化 
AsyncContext， 且 传 入 的 请 求 是 HttpServletRequest 的 一 个 实例 ， 则 使 用 
HttpServletRequest.getRequestURI() 返回 的 URI 进行 分 派 。 否 则 分 派 的 是 容器 最 后 分 
派 的 请 求 URI。 下 面 的 代码 示例 2-1， 代 码 示 例 2-2 和 代码 示例 2-3 演 示 了 不 同情 况 下 分 派 
的 目标 URI 是 什么 。 


CODE EXAMPLE 2-1 


// REQUEST to /url/A 
AsyncContext ac = request.startAsync(); 


ac.dispatch(); // ASYNC dispatch to /url/A 


CODE EXAMPLE 2-2 


// REQUEST to /url/A 

// FORWARD to /url/B 
request.getRequestDispatcher(“/url/B").forward(request, 
response); 

// Start async operation from within the target of the FORWARD 
AsyncContext ac = request.startAsync(); 

ac.dispatch(); // ASYNC dispatch to /url/A 


CODE EXAMPLE 2-3 


// REQUEST to /url/A 

// FORWARD to /url/B 
request.getRequestDispatcher(“/url/B").forward(request, 
response); 

// Start async operation from within the target of the FORWARD 
AsyncContext ac = request.startAsync(request, response); 
ac.dispatch(); // ASYNC dispatch to /url/B 


e public void dispatch(ServletContext context, String path) -将 用 于 初始 化 AsyncContext 
的 请 求 和 响应 分 派 到 指定 ServletContext 的 指定 路 径 的 资源 。 

e 上 面 定义 了 dispatch 方法 的 全 部 3 个 变 体 ， 调 用 这 些 方法 且 将 请 求 和 响应 对 象 传 入 到 容器 
的 一 个 托管 线程 后 将 立即 返回 ， 在 托管 线程 中 异步 操作 将 被 执行 。 请 求 的 分 派 器 类 型 设 
置 为 异步 (ASYNC) 。 不 同 于 RequestDispatcher.forward(ServletRequest, 
ServletResponse) 分 派 ， 响 应 的 缓冲 区 和 头 信息 将 不 会 重 置 ， 即 使 响应 已 经 被 提交 分 派 
也 是 合法 的 。 控 制 委 托 给 分 派 目 标的 请 求 和 响应 ， 除 非 调 用 了 
ServletRequest.startAsync() 或 ServletRequest.startAsync(ServletRequest, 
ServletResponse)， 否 则 响应 将 在 分 派 目标 执行 完成 时 被 关闭 。 在 调用 了 startAsync + 
法 的 容器 启动 的 分 派 没有 返回 到 容器 之 前 任何 dispatch 方 法 的 调用 将 没有 任何 作用 。 
A onComplete(AsyncEvent), AsyncListener. onumćoni enormno 和 
人 onError(AsyncEvent) 的 调用 将 被 延迟 到 容器 司 动 的 分 派 返回 到 容器 之 
后 。 通 过 调用 ServletRequest.startAsync. 启 动 pe 期 至 多 只 有 一 个 异步 分 派 操 
作 。 相 同 的 异步 周期 内 任何 试图 执行 其 他 的 异步 分 派 操作 是 非法 的 并 将 导致 抛 出 
lllegalStateException。 如 果 后 来 在 已 分 派 的 请 求 上 调用 startAsync， 那 么 所 有 的 
dispatch 方法 调用 将 和 之 上 具有 相同 的 限制 。 

e 任何 在 执行 dispatch 方法 期 间 可 能 抛 出 的 错误 或 异常 必须 由 容器 抓 住 和 处 理 ， 如 下 所 
es 


o i. 调用 所 有 由 AsyncContext 创 建 的 并 注册 到 ServletRequest 的 AsyncListener 实例 的 
AsyncListener.onError(AsyncEvent) 方法 ， 可 以 通过 AsyncEvent.getThrowable() 获 
取 到 捕获 的 Throwable 。 

o ji, 如 果 没 有 监听 器 调用 AsyncContext.complete 或 任何 AsyncContext.dispatch 方 
法 ， 然 后 执行 一 个 状态 码 为 
HipSeMeIR Sponse: SC_INTERNAL_ SERVER_ERROR 的 出 错 分 派 ， 并 且 可 以 通 

过 RequestDispatcher ERROR_EXCEPTION 请 求 属 性 获取 Throwable 值 。 
o ili. 如 果 没 有 找到 匹配 的 错误 页 面 ， 或 错误 页 面 没 有 调用 AsyncContext.complete() 或 
任何 AsyncContext.dispatch 方法 ， 则 容器 必须 调用 AsyncContext.complete 。 
= public boolean hasOriginalRequestAndResponse() — 该 方法 检查 AsyncContext 
是 否 以 原始 的 请 求 和 响应 对 象 调 用 ServletRequest.startAsync() 完 成 初始 化 的 ， 
或 者 是 否 通 过 调用 ServletRequest.startAsync(ServletRequest, 
ServletResponse) 完 成 初始 化 的 ， 且 传 入 的 ServletRequest 和 ServletResponse 
Gene 用 提供 的 包装 器 ， 这 样 的 话 将 返回 true。 如 果 AsyncContext 使 用 
包装 的 请 求 及 (或 ) 响应 对 ain Fl ServletRequest.startAsync(ServletRequest, 
Som ee Pon 0 ， 那么 将 返回 false。 在 请 求 处 于 异步 模式 后 ， 该 
息 可 以 被 出 站 方向 调用 的 过 滤器 使 用 ， 用 于 决定 是 否 在 入 站 调用 时 添加 的 请 
an (或 ) 响应 包装 器 需要 在 异步 操作 期 间 被 维持 或 者 被 释放 。 
= public void start(Runnable r) — a ， 该 线程 可 能 来 自 
托管 的 线程 池 ， 用 于 运行 指定 的 Runnable 对 象 。 容 器 可 能 传播 相应 的 上 下 文 信 
息 到 该 Runnable 对 象 。 
= public void complete() — 如 果 调 用 了 request.startAsync， 则 必须 调用 该 方法 以 

完成 异步 处 理 并 提交 和 关闭 响应 。 如 果 请 求 分 派 到 一 个 不 支持 异步 操作 的 

Servlet， 或 者 由 AsyncContext.dispatch 调 用 的 目标 servlet 之 后 没有 调用 

startAsync， 则 complete 方法 会 由 容器 调用 。 这 种 情况 下 ， 容 器 负责 当 servlet 

的 service 方法 一 退出 就 调用 complete()。 如 果 startAsync ey 则 必须 

抛 出 IllegalStateException。 在 调用 ServletRequest.startAsync() 或 

ServletRequest.startAsync(ServletRequest, ServletResponse) 之 后 且 在 调用 任 

意 dispatch 方法 之 前 的 任意 时 刻 调用 complete() 是 合法 的 。 在 调用 了 

startAsync 方法 的 容器 启动 的 分 派 没有 返回 到 容器 之 前 该 方法 的 调用 将 没有 任 

何 作 用 。AsyncListeneronComplete(AsyncEvent) 的 调用 将 被 延迟 到 容器 局 动 

的 分 派 返回 到 容器 之 后 。 

ServietRequestWrapper 


see boolean isWrapperFor(ServletRequest req)- 检查 该 包装 器 是 否 递归 的 包 
给 定 的 ServletRequest， 如 果 是 则 返回 true > FNA false ° 
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5 
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定 的 ServletResponse， 如 果 是 则 返回 true > FM 


= public void onComplete(AsyncEvent event) — 用 于 通知 监听 器 在 Servlet Le a 


的 异步 操作 完成 了 。 

= public void onError(AsyncEvent event) — 用 于 通知 监听 器 异步 操作 未 能 完成 。 

= public void onStartAsync(AsyncEvent event) — 用 于 通知 监听 器 正在 通过 调用 一 
个 ServletRequest.startAsync 方法 启动 一 个 新 的 异步 周期 。 正 在 被 重新 启动 的 
异步 操作 对 应 的 AsyncContext 可 以 通过 调用 给 定 的 event 上 调用 
AsyncEvent.getAsyncContext 获取 。 

u 在 异步 操作 超时 的 情况 下 ， 容 器 必须 按照 如 下 步骤 运行 : 

u 当 异 步 操 作 启 动 后 调用 注册 到 ServietRequest 的 所 有 AsyncListener 实例 的 
AsyncListener.onTimeout 方法 。 

如 果 没 有 监听 器 调用 AsyncContext.complete() 或 任何 AsyncContext.dispatch 
方法 ， 执 行 一 个 状态 码 为 
HttpServletResponse.SC_INTERNAL_SERVER_ERROR 出 错 分 派 。 

u 如 果 没 有 找到 匹配 的 错误 页 面 ， 或 者 错误 页 面 没有 调用 
AsyncContext.complete() 或 任何 AsyncContext.dispatch 方法 ， 则 容器 必须 调用 
AsyncContext.complete() » 

=" 如 果 在 AsyncListener 中 调用 方法 抛 出 异常 ， 将 记录 下 来 且 将 不 影响 任何 其 他 
AsyncListener 的 调用 。 

u 默认 情况 下 是 不 支持 JSP 中 的 异步 处 理 ， 因 为 它 是 用 于 内 容 生 成 且 异 步 处 理 可 
能 在 内 容 生 成 之 前 已 经 完成 。 这 取决 于 容器 如 何 处 理 这 种 情况 。 一 旦 完成 了 所 
有 的 异步 活动 ， 使 用 AsyncContext.dispatch 分 派 到 的 ISP 页 面 可 以 用 来 生成 

m 下 面 所 示 的 图 2-1 描 述 了 各 种 异步 操作 的 状态 转换 。 


FIGURE 2-1 State transition diagram for asynchronous operations 
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线程 安全 


除了 startAsync 和 complete 方法 ， 请 求 和 响应 对 象 的 实现 都 不 保证 线程 安全 。 这 意味 着 它们 
应 该 仅 在 请 求 处 理 线程 范围 内 使 用 或 应 用 确保 线程 安全 的 访问 请 求 和 响应 对 象 。 


如 果 应 用 使 用 容器 管理 对 象 创建 一 个 线程 ， 例 如 请 求 或 响应 对 象 ， 这 些 对 象 必 须 在 其 生命 周 
期 内 被 访问 ， 就 像 定 义 在 3.12 节 的 “请求 对 象 的 生命 周期 "和 5.7 节 的 “响应 对 象 的 生产 周期 "。 请 
注意 ， 除 了 startAsync 和 complete 方法 ， 请 求 和 响应 对 象 不 是 线程 安全 的 。 如 果 这 些 对 象 需 
要 多 线程 访问 ， 需 要 同步 这 些 访问 或 通过 包装 器 添加 线程 安全 语义 ， 比 如 ， 同 步 化 调用 访问 
请 求 属性 的 方法 ， 或 者 在 线程 内 为 响应 对 象 使 用 一 个 局 部 输出 流 。 


升级 处 理 


ey 1° Upgrade 通用 头 允 许 客 户 端 指定 其 支持 和 硕 望 使 用 的 其 他 通信 协议 。 如 果 服 务 
器 找到 合适 的 切换 协议 ， 那 么 新 daj: 的 通信 中 使 用 。Servle t 容 器 提供 了 HTTP 升 

级 机 制 。 不 过 ，Servlet 容器 本 身 不 知道 任何 升级 协议 。 URA ERT 在 HttpUpgradeHandler 

协议 处 理 器 。 在 容器 和 HttpUpgradeHandler 协议 处 理 器 之 间 通 过 字 节 流 进行 数据 读 取 或 写 

Ao 


当 收 到 一 个 升级 请 求 ，servlet 可 以 调用 HttpServletRequest.upgrade 方 法 启动 升级 处 理 。 该 
方法 实例 化 给 定 的 HttpUpgradeHandler 类 ， 返 回 的 HttpUpgradeHandler 实例 可 以 被 进 一 
的 定制 。 应 用 准备 和 发 送 一 个 合适 的 响应 到 客户 端 ? 退出 servlet service 方法 之 后 ，servlet 
容器 完成 所 有 过 滤器 的 处 理 并 标记 连接 已 交 给 HttpUpgradeHandler 协议 处 理 器 处 理 。 然 后 调 
用 HttpUpgradeHandler 协议 处 理 器 的 init 方法 ， 传 入 一 个 WebConnection 以 允许 
HttpUpgradeHandler 协议 处 理 器 访问 数据 流 。 


Servlet 过 滤器 仅 处 理 初始 的 HTTP 请 求 和 响应 ， 然 后 它们 将 不 会 再 参与 到 后 通信 中 。 换 
匈 话 说， 一旦 请 求 被 升级 ， 它 们 将 不 会 被 调用 。 


HttpUpgradeHandler 可 以 使 用 非 阻 塞 IO (non blocking IO) 消费 和 生产 消息 。 


当 处 理 HTTP 升级 时 ， 开 发 人 员 负 责 线程 安全 的 访问 ServletlnputStream 和 
ServietOutputStream ° 


当 升 级 处 理 已 经 完成 ， 将 调用 HttpUpgradeHandler.destroy 方法 


服务 的 终止 


servlet 容器 没 必 要 保持 装载 的 servlet 持续 任何 特定 的 一 段 时 间 。 一 个 servlet 实例 可 能 会 在 
servlet 容器 内 保持 活跃 (active) 持续 一 段 时 间 (以 毫秒 为 单位 ) ，servlet 容 器 的 寿命 可 能 是 
几 天 ， 几 个 月 ,或 几 年 ， 或 者 是 任何 之 间 的 时 间 。 


当 servlet 容器 确定 servlet 应 该 从 服务 中 移 除 时 ， 将 调用 Servlet 接口 的 destroy 方法 以 允许 
servlet 释放 它 使 用 资源 和 保存 任何 持久 化 的 状态 。 例 如 ， 当 想 要 节省 内 存 资 源 或 它 被 
关闭 时 ， 容 器 可 以 做 这 


在 serviet 容器 调用 destroy 方法 之 前 ， 它 必须 让 当前 正在 执行 Service 方法 的 任何 线程 完成 执 
行 ， 或 者 超过 了 服务 器 定义 的 时 间 限 制 。 


EAA T servlet 实例 的 destroy 方法 ， 容 器 无 法 再 路 由 其 他 请 求 到 该 servlet 实例 了 。 如 果 
容器 需要 再 次 使 用 该 servlet， 它 必须 用 该 servlet 类 的 一 个 新 的 实例 。 在 destroy 方法 完成 
Ja > servlet 容器 必须 释放 servlet 实例 以 便 被 垃圾 回收 。 


器 请 求 的 HTTP 头 部 和 消息 体 。 


请 求 对 象 封装 了 客户 端 请 求 的 所 有 信息 。 在 HTTP 协议 中 ， 这 些 人 


HTTP 协议 参数 


servlet 的 请 求 参 数 以 字符 串 的 形式 作为 请 求 的 一 部 分 从 客户 端 发 送 到 servlet 容器 。 当 请 求 是 
一 个 HttpServletRequest 对 象 ， 且 符合 “参数 可 用 时 "描述 的 条 件 时 ， 容 器 从 URI 坦 kih 字符 串 
和 POST 数据 中 填充 参数 。 参 数 以 一 系列 的 名 - 值 对 (name-value) 的 形式 保存 。 任 何 给 定 的 
参数 的 名 称 可 存在 多 个 参数 值 。ServletRequest 接口 的 下 列 方法 可 访问 这 些 参数 : 


e getParameter 

e getParameterNames 
e getParameterValues 
e getParameterMap 


getParameterValues 方法 返回 一 个 String 对 象 的 数组 ， 包 含 了 与 参数 名 称 相关 的 所 有 参数 
值 。getParameter 方法 的 返回 值 必 须 是 getParameterValues 方法 返回 的 String 对 象 数 组 中 的 
第 一 个 值 。getParameterMap 方法 返回 请 求 参数 的 一 个 java.util.Map 对 象 ， 其 中 以 参数 名 称 
作为 map 键 ， 参 数值 作为 map 值 。 


查询 字符 串 和 POST 请 求 的 数据 被 汇总 到 请 求 参数 集合 中 。 查 询 字 符 串 数据 放 在 POST 数据 
之 前 。 例 如 ， 如 果 请 求 由 查询 字符 串 a=hello 和 POST 数据 a=goodbye&a=world 组 成 ， 得 到 
的 参数 集合 顺序 将 是 a=(hello, goodbye, world) ° 


这 些 API 不 会 暴露 GET HR (HTTP 1.1 所 定义 的 ) 的 路 径 参 数 。 他 们 必须 从 
getRequestURI 方法 或 getPathlnfo 方法 返回 的 字符 串 值 中 解析 。 


当 参 数 可 用 时 
Post 表单 数据 能 填充 到 参数 集 (Paramter Set) 前 必须 满足 的 条 件 : 


1. 该 请 求 是 一 个 HTTP 或 HTTPS 请 求 。 

2. HTTP 方法 是 POST ° 

3. ASA Š application/x-www-form-urlencoded ° 

4. 该 servlet 已 经 对 请 求 对 象 的 任意 getParameter 方法 进行 了 初始 调用 。 


如 果 不 满足 这 些 条 件 ， 而 且 参 数 集中 不 包括 post 表单 数据 ， 那 么 servlet 必须 可 以 通过 请 求 
对 象 的 输入 流 得 至 aa 数据 。 如 果 满 足 这 些 条 件 ， 那 么 从 请 求 对 象 的 输入 流 中 直接 读 取 post 
数据 将 不 再 有 效 


LAE 


当 数 据 以 multipart/form-data 的 格式 发 送 时 ，servlet 容器 支持 文件 上 传 。 


如 果 满 足以 下 任何 一 个 条 件 ，servlet 容器 提供 multipart/form-data 格式 数据 的 处 理 。 


e Servlet 处 理 的 请 求 使 用 了 第 8.1.5 节 定义 的 注解 omultipartconfig ° 
e 为 了 servlet 处 理 请 求 ， 部 署 描述 符 包 含 了 一 个 multipart-config ZLE > 
请 求 中 的 multipart/form-data 类 型 的 数据 如 何 可 用 ， 取 决 于 servlet 容器 是 否 提供 
multipart/form-data 格式 数据 的 处 理 : 
* 如 果 servlet 容器 提供 multipart/form-data 格式 数据 的 处 理 ， 可 通过 HttpServletRequest 
中 的 以 下 方法 得 到 : 


o public Collection getParts() 
o public Part getPart(String name) 每 个 part 都 可 通过 Part.getInputStream 方法 访问 
头 部 ， 相 关 的 内 容 类 型 和 内 容 。 对 于 表单 数据 的 Content-Disposition， 即 使 没有 文 
件 名 ， 也 可 使 用 part 的 名 称 通过 HttpServletRequest 的 getParameter 和 
getParameterValues 方法 得 到 part 的 字符 串 值 。 
* 如 果 servlet 的 容器 不 提供 multi-part/form-data 格式 数据 的 处 理 ， 这 些 数据 将 可 通 


HttpServletReuqest.getinputStream 得 到 。 


属性 


属性 是 与 请 求 相 关联 的 对 象 。 属 性 可 以 由 容器 设置 来 表达 人 信息， 否则 无 法 通过 API 表示 ， 或 
者 由 servlet 设置 将 信息 传达 给 另 一 个 servlet (通过 RequestDispatcher) 。 属 性 通过 
ServietRequest 接口 中 下 面 的 方法 来 访问 : 


e getAttribute 
e getAttributeNames 
e setAttribute 


一 个 属性 名 称 只 能 关联 一 个 属性 值 。 


前 级 java. 和 javax. 开头 的 属性 名 称 是 本 规范 的 保留 定义 。 同 样 地 ， 前 级 sun. 和 com.sun.， 
oracle 和 com.oracle 开头 的 属性 名 是 Oracle Corporation 的 保留 定义 。 建 议 属性 集中 所 有 属 
性 的 命名 与 Java 编 程 语言 的 规范 为 包 命 名 建议 的 反 向 域名 约定 一 致 。 


K 
通过 下 面 的 HttpServletRequest 接口 方法 ，servlet 可 以 访问 HTTP 请 求 的 头 信息 : 


e getHeader 
e getHeaders 
e getHeaderNames 


getHeader 方法 返回 给 定 头 名 称 的 头 。 多 个 头 可 以 具有 相同 的 名 称 ， 例 如 HTTP 请 求 中 的 
Cache-Control 头 。 如 果 多 个 头 的 名 称 相 同 ，getHeader 方 法 返回 请 求 中 的 第 一 个 头 。 
getHeaders 方法 允许 访问 所 有 与 特定 头 名 称 相关 的 头 值 ， 返 回 一 个 String HHA 
Enumeration ( 枚 举 ) 。 头 可 包含 由 String 形式 的 int 或 Date 数据 。HttpServletRequest 接 
口 提供 如 下 方便 的 方法 访问 这 些 类 型 的 头 数据 : 


e getlntHeader 
e getDateHeader 


如 果 getIntHeader 方法 不 能 转换 为 int 的 头 值 ， 则 抛 出 NumberFormatException 异常 。 如 果 
getDateHeader 方法 不 能 把 头 转换 成 一 个 Date 对 象 ， 则 抛 出 IllegalArgumentException + 


Era 
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请 求 路 径 元 素 


引导 servlet 服务 请 求 的 请 求 路 径 由 许多 重要 部 分 组 成 。 以 下 元 素 从 请 求 URI 路 径 得 到 ， 并 通 
过 请 求 对 象 公开 : 


> 


* Context Path : 5 ServletContext 相关 联 的 路 径 前 组 是 这 个 servlet 的 一 部 分 。 如 果 这 
上 下 文 是 基于 Web 服务 器 的 URL 命名 空间 基础 上 的 "默认 ”上 下 文 ， 那 么 这 个 路 径 将 是 
个 空 字符 串 。 和 否则 ， 如 果 上 下 文 不 是 基于 服务 器 的 命名 空间 ， 那 么 这 个 路 径 以 / 字符 开 
始 ， 但 不 以 /字符 结 
e Servlet Path : 路 径 部 分 直接 与 激活 请 求 的 映射 对 应 。 这 个 路 径 以 “ 放 "字符 开头 ， 如 果 请 求 
与 9 **” 或 ”模式 匹配 ， 在 这 种 情况 下 ， 它 是 一 个 空 字符 串 。 
e Pathlnfo : 请 求 路 径 的 一 部 分 ， 不 属于 Context Path 或 Servlet Path。 如 果 没 有 额外 的 路 
径 ， 它 要 么 是 null， 要 么 是 以 开 头 的 字符 串 。 使 用 HttpServletRequest 接口 中 的 下 面 方 
法 来 访问 这 些 信息 : 


e getContextPath 


e getServletPath 
e getPathlnfo 


重要 的 是 要 注意 ， 除 了 请 求 URI 和 路 径 部 分 的 URL 编码 差异 外 ， 下 面 的 等 式 永 远 为 真 : 


requestURI = contextPath + servletPath + pathInfo 


举 几 个 例子 来 解析 上 述 各 点 ， 请 考虑 以 下 几 点 : 


TABLE 3-1 Example Context Set Up 


Context Path /catalog 
Servlet Mapping Pattern: /lawn/* Servlet: LawnServlet 
Servlet Mapping Pattern: /garden/* Servlet: GardenServlet 
Servlet Mapping Pattern: *.jsp Servlet: JSPServiet 


遵守 下 列 行为 : 


TABLE 3-2 Observed Path Element Behavior 


请 求 路 径 路 径 元 素 


ContextPath: /catalog ServletPath: /lawn Pathinfo: 


/catalog/lawn/index.html /index.html 


ContextPath: /catalog ServletPath: /garden PathInfo: 


/catalog/garden/implements/ /implements/ 


ContextPath: /catalog ServletPath: /help/feedback.jsp 


/catalog/help/feedback.jsp Pathinfo: null 


路 径 转 换 方法 


在 API 中 有 两 个 方便 的 方法 ， 允 许 开发 者 获得 与 菜 个 特定 的 路 径 等 价 的 文件 系统 路 径 些 
方法 是 : 


e ServietContext.getRealPath 
e HttpServletRequest.getPathTranslated 


getRealPath 方法 需要 一 个 String 参数 ， 并 返回 一 个 String 形式 的 路 径 ， 这 个 路 径 对 应 一 个 
在 本 地 文件 系统 上 的 文件 。getPathTranslated 方 法 推断 出 请 求 的 pathlnfo 的 实际 路 径 。 这 些 
方法 在 servlet 容器 无 法 确定 一 个 有 效 的 文件 路 径 的 情况 下 ， 如 Web 应 用 程序 从 归档 中 ， 在 

不 能 访问 本 地 的 远程 文件 系统 上 ， 或 在 一 个 数据 库 中 执行 时 ， 这 些 方法 必须 返回 null e JAR 
文件 中 ee 目录 下 的 资源 ， 只 有 当 调 用 getRealPath() 方法 时 才 认 为 容器 
经 从 包含 它 的 JAR 文件 中 解压 ， 在 这 种 情况 下 ， 必 须 返 回 解压 缩 后 位 置 。 


非 阻塞 IO 


Web 容器 中 的 非 阻塞 请 求 处 理 有 助 于 提高 对 改善 Web 容器 可 扩展 性 不 断 增加 的 需求 ， 增 加 
Web 容器 可 同时 处 理 请 求 的 连接 数量 。servlet 容器 的 非 阻 塞 IO 允许 开发 人 员 在 数据 可 用 时 
读 取 数 据 或 在 数据 可 写 时 写 数据 。 非 阻塞 |O 仅 对 在 Servlet 和 Filter (2.3.3.3 节 定义 的 ，“ 异 
GRE”) 中 的 异步 请 求 处 理 和 升级 处 理 (2.3.3.5 节 定义 的 ，“ 升 级 处 理 ”) HK BM > 4H 
用 ServletlnputStream.setReadListener 或 ServletOutputStream.setWriteListener 方法 时 将 抛 
i: IllegalStateException ° 


ReadListener 为 非 阻 塞 ID 提供 了 下 面 的 回调 方法 : 


e ReadListener 

o onDataAvailable(). 当 可 以 从 传 入 的 请 求 流 中 读 取 数据 时 ReadListener 的 
onDataAvailable 方法 被 调用 。 当 数据 可 读 时 容器 初次 调用 该 方法 。 当 且 仅 当下 面 描 
述 的 ServietInputStream 的 isReady 方法 返回 false， 容 器 随后 将 调用 
onDataAvailable 方法 。 

o onAllIDataRead(). 当 读 取 完 注册 了 此 监听 器 的 ServletRequest 的 所 有 数据 时 调用 
onAllDataRead 方法 。 

o onError(Throwable t). 处 理 请 求 时 如 果 有 任何 错误 或 异常 发 生 时 调用 onError 方法 。 


容器 必须 线程 安全 的 访问 ReadListener 中 的 方法 。 
除了 上 述 ReadListener 定义 的 方法 外 ， 下 列 方法 已 被 添加 到 ServletInputStream 类 中 : 


e ServletlnputStream 

o boolean isFinished(). ServietInputStream 相关 的 请 求 的 所 有 数据 已 经 读 取 完 时 
isFinished 方法 返回 true ° 否则 返回 false ° 

o boolean isReady(). 如 果 可 以 无 阻塞 地 读 取 数 据 isReady 方法 返回 true。 如 果 没 有 数 
据 可 以 无 阻塞 地 读 取 该 方法 返回 false ° t RisReady 方法 返回 false > HWA read 方 
法 是 非法 的 ， 且 必须 抛 出 lllegalStateException ° 

o void setReadListener(ReadListener listener). 设置 上 述 定义 的 ReadListener， 调 用 
它 以 非 阻塞 的 方式 读 取 数 据 。 一 旦 把 监听 器 与 给 定 的 ServletlnputStream 关联 起 
来 ， 当 数据 可 以 读 取 ， 所 有 的 数据 都 读 取 完 或 如 果 处 理 请 求 时 发 生 错误 ， 容 器 调用 
ReadListener 的 方法 。 注 册 一 个 ReadListener 将 启动 非 阻塞 ID。 在 那 时 切换 到 传 
统 的 阻塞 IO 是 非法 的 ， 且 必须 抛 出 lllegalStateException。 在 当前 请 求 范围 内 ， 随 后 
调用 setReadListener 是 非法 的 且 必 须 抛 出 |llegalStateException ° 


Cookie 


HttpServletRequest 接口 提供 了 getCookies 方法 来 获得 请 求 中 的 cookie 的 一 个 数组 。 这 些 
cookie 是 从 客户 端 发 送 到 服务 器 端的 客户 端 发 出 的 每 个 请 求 上 的 数据 。 典 型 地 ， 客 户 端 发 送 
回 的 作为 cookie 的 一 部 分 的 唯一 信息 是 cookie 的 名 称 和 cookie 值 。 当 cookie 发 送 到 浏览 器 
时 可 以 设置 其 他 cookie 属性 ， 诸 如 注释 ， 这 些 信息 不 会 返回 到 服务 器 。 该 规范 还 允许 的 
cookies Æ HttpOnly cookie ° HttpOnly cookie 暗示 客户 端 它们 不 会 暴露 给 客户 端 脚 本 代码 

( 它 没 有 被 过 滤 掉 ， 除 非 客 户 端 知道 如 何 查找 此 属性 ) 。 使 用 HttpOnly cookie 有 助 于 减少 某 
些 类 型 的 跨 站 点 脚本 攻击 。 


SSL 属性 


如 果 请 求 已 经 是 通过 一 
isSecure 方法 公开 该 


个 安全 协议 发 送 ， 如 HTTPS， 必 须 通 过 ServletRequest 接口 的 
信息 。Web 容器 必须 公开 下 列 属 性 给 servlet 程序 员 : 


TABLE 3-3 Protocol Attributes 


属性 属性 名 称 Java 类 型 
密码 套件 javax.servlet.request.cipher_suite String 
算法 的 位 大 小 javax.servlet.request.key_size Integer 
SSL A% id javax.servlet.request.ssl_session_id String 


如 果 有 一 个 与 请 求 相 关 的 SSL 证 书 ， 它 必须 由 servlet 容器 以 
java.security.cert.X509Certificate 类 型 的 对 象 数组 暴露 给 servlet 程序 员 并 可 通过 一 个 
javax.servlet.request.X509Certificate 类 型 的 ServletRequest 属 性 访问 。 


这 个 数组 的 顺序 是 按照 信任 的 升序 顺序 。 证 书 链 中 的 第 一 个 证 书 是 由 客户 端 设 置 的 ， 第 二 


是 用 来 验证 第 一 个 的 , 等 等 s 


国际 化 


客户 可 以 选择 希望 Web 服务 器 用 什么 语言 来 响应 。 该 信息 可 以 和 使 用 Accept-Language *4 
HTTP/1.1 规范 中 描述 的 其 他 机 制 的 客户 端 通 信 。ServletRequest 接口 提供 下 面 的 方法 来 确定 
发 送 者 的 首选 语 言 环境 : ; 


e getLocale 
e getLocales 


getLocale 方法 将 返回 客户 端 要 接受 内 容 的 首选 语言 环境 。 要 了 解 更 多 关于 Accept-Language 
头 必须 被 解释 为 确定 客户 端 首选 语言 的 信息 ， 请 参阅 RFC 2616 (HTTP/1.1) 14.4 节 。 


Aenea Arete E —~* Locale *t #4 Enumeration (4&4) > on 言 环境 开始 顺序 递 
减 ， 些 语 E > is i re] KEP HES IS 言 环 境 。 如 果 客 户 端 没 有 指定 首 选 语 言 环 境 ? 

a ee 方法 返回 的 语言 环境 必须 是 servlet 容器 默认 的 语言 环境 ， 而 getLocales 方法 必须 
Vv 


返回 只 包含 一 个 默认 语言 环境 的 Local 元 素 的 枚 举 。 


请 求 数据 编码 


目前 ， 许 多 浏览 器 不 随 着 Content-Type 头 一 起 发 送 字 符 编 码 限定 符 ， 而 是 根据 读 取 HTTP 请 
求 确定 字符 编码 。 如 果 客 户 端 请 求 没有 指定 请 求 默 认 的 字符 编码 ， 容 器 用 来 创建 请 求 读 取 器 
和 解析 POST 数据 的 编码 必须 是 “ISO-8859-1"。 然 而 ， 为 了 向 开发 人 员 说 明 客户 端 没 有 指定 
请 求 默认 的 字符 编码 ， 在 这 种 情况 下 ， 客 户 端 发 送 字符 编码 失败 ， 容 器 从 
getCharacterEncoding 方法 返回 null。 


如 果 客 户 端 没 有 设置 字符 编码 ， 并 使 用 不 同 的 编码 来 编码 请 求 数据 ， 而 不 是 使 用 上 面 描述 的 

默认 的 字符 编码 ， 那 么 可 能 会 发 生 问 题 。 为 了 弥补 这 种 情况 ，ServletRequest 接口 添加 了 一 

个 新 的 方法 setCharacterEncoding(String enc)。 开 发 人 员 可 以 通过 调用 此 方法 来 覆盖 由 容器 
提供 的 字符 编码 。 必 须 在 解析 任何 post 数据 或 从 请 求 读 取 任 何 输入 之 前 调用 此 方法 。 此 方法 
一 旦 调用 ， 将 不 会 影响 已 经 读 取 的 数据 的 编码 。 


请 求 对 象 生命 周 期 


每 个 请 求 对 象 只 在 一 个 Servlet 的 service 方法 的 作用 域内 ， 或 过 滤器 的 doFilter 方法 的 作用 
域内 有 效 ， 除 非 该 组 件 启用 了 异步 处 理 并 且 调 用 了 请 求 对 象 的 startAsync 方法 。 在 发 生 异 步 
处 理 的 情况 下 ， 请 求 对 象 一 直 有 效 ， 直 到 调用 AsyncContext 的 complete 方法 。 容 器 通常 会 
重复 利用 请 求 对 象 ， 以 避免 创建 请 求 对 象 而 产生 的 性 能 开销 。 开 发 人 员 必 须 注意 的 是 ， 不 建 
议 在 上 述 范 围 之 外 保持 startAsync 方法 还 没有 被 调用 的 请 求 对 象 的 引用 ， 因 为 这 样 可 能 产生 
不 确定 的 结果 。 


在 升级 情况 下 ， 如 上 描述 仍 成 立 。 


ServletContext 接口 介绍 


ServletContext 接口 定义 了 servlet 运行 在 的 Web 应 用 的 视图 。 容 器 供应 商 负责 提供 servlet 
容器 的 ServletContext 接口 的 实现 。servlet 可 以 使 用 ServletContext 对 象 记 录 事 件 ， 获 取 
URL 引用 的 资源 ， 存 取 当 前 上 下 文 的 其 他 servlet 可 以 访问 的 属性 。 


ServietContext 是 Web 服务 器 中 已 知 路 径 的 根 。 例 如 ，servlet 上 下 文 可 以 从 
http://www.mycorp.com/catalog 找 出 ，/catalog 请 求 路 径 称 为 上 下 文 路 径 ， 所 有 以 它 开 头 的 请 
求 都 会 被 路 由 到 与 ServletContext 相关 联 的 Web 应 用 。 


ServletContext 接口 作用 域 


每 一 个 部 署 到 容器 的 Web 应 用 都 有 一 个 ServletContext 接口 的 实例 与 之 关联 。 在 容器 分 布 在 
多 台 上 庶 拟 机 的 情况 下 ， 每 个 JVM 的 每 个 Web 应 用 将 有 一 个 ServletContext 实例 。 


如 果 容 器 内 的 Servlet 没有 部 署 到 Web 应 用 中 ， 则 隐 含 的 作为 “默认 ”Web 应 用 的 一 部 分 ， 并 
有 一 个 默认 的 ServletContext 。 在 分 布 式 的 容器 中 ， 默 认 的 ServletContext 是 非 分 布 式 的 且 
仅 存 在 于 一 个 JVM 中 。 


初始 化 参数 


如 下 ServletContext 接口 方法 允许 servlet 访问 由 应 用 开发 人 员 在 Web 应 用 中 的 部 署 描述 符 中 
指定 的 上 下 文 初 始 化 参数 : 

e getinitParameter 

e getinitParameterNames 


应 用 开发 人 员 使 用 初始 化 参数 来 表达 配置 信息 。 代 表 性 的 例子 是 一 个 网 络 管理 员 的 e-mail 地 
址 ， 或 保存 关键 数据 的 系统 名 称 。 


配置 方法 


下 面 的 方法 从 Servlet 3.0 开始 添加 到 ServletContext， 以 便 启 用 编程 方式 定义 Servlet ` Filter 
和 它们 映射 到 的 url 模式 。 这 些 方法 只 能 从 ServletContextListener 实现 的 contexlnitialized 
方法 或 者 ServletContainerlnitializer 实现 的 onStartup 方法 进行 的 应 用 初始 化 过 程 中 调用 。 除 
了 添加 Servlet 和 Filter， 也 可 以 查找 关联 到 Servlet 或 Filter 的 一 个 Registration 对 象 实例 ， 
或 者 到 Serviet 或 Filter 的 所 有 Registration 对 象 的 map。 如 果 ServietContext 传 到 了 
ServietContextListener 的 contextlnitialized 方法 ， 但 该 ServletContextListener 即 没有 在 
web.xml 或 web-fragment.xml 中 声明 也 没有 使 用 @WebListener 注解 ， 则 在 ServletContext 
中 定义 的 用 于 Servlet ` Filter 和 Listener 的 编程 式 配置 的 所 有 方法 必须 抛 出 
UnsupportedOperationException ° 


编程 式 添 加 和 配置 Servlet 


编程 式 添 加 Servlet 到 上 下 文 对 框架 开发 者 是 很 有 用 的 。 例 如 ， 框 架 可 以 使 用 这 个 方法 声明 一 
个 控制 器 servlet。 这 个 方法 将 返回 一 个 ServletRegistration 或 ServletRegistration.Dynamic 
对 象 ， 允 许 我 们 进一步 配置 如 init-params > url-mapping 等 Servlet 的 其 他 参数 。 下 面 描述 了 
该 方法 的 三 个 重 载 版 本 。 

addServlet(String servletName, String className) 

该 方法 允许 应 用 以 编程 方式 声明 一 个 servlet。 它 添加 给 定 的 servlet 名 称 和 class 名 称 到 servlet 
上 下 文 

addServlet(String servietName, Servlet servlet) 

该 方法 允许 应 用 以 编程 方式 声明 一 个 Servlet。 它 添加 给 定 的 名 称 和 Servlet 实例 的 Servlet 到 
servlet 上 下 文 。 

addServlet(String servietName, Class <? extends Servlet> 
servletClass) 

该 方法 允许 应 用 以 编程 方式 声明 一 个 Servlet。 它 添加 给 定 的 名 称 和 Servlet 类 的 一 个 实例 的 


Servlet 到 servlet EF x 


T createServlet(Class clazz) 


该 方法 实例 化 一 个 给 定 的 Servlet class， 该 方法 必须 支持 适用 于 Servlet 的 除了 @WebServiet 
的 所 有 注解 。 返 回 的 Servlet 实例 通过 调用 上 边 定义 的 addServlet(String, Servlet) 注册 到 
ServletContext 之 前 ， 可 以 进行 进一步 的 定制 。 


ServietRegistration getServietRegistration(String 
servletName) 


该 方法 返回 与 指定 名 字 的 Servlet 相关 的 ServletRegistration， 或 者 如 果 没 有 该 名 字 的 
ServietRegistration 则 返回 null。 如 果 ServletContext 传 到 了 ServietContextListener 的 
contextlnitialized 方法 ， 但 该 ServletContextListener 即 没 有 在 web.xml 或 web-fragment.xml 
中 声明 也 没有 使 用 javax.servlet.annotation.WebListener 注解 ， 则 必须 抛 出 
UnsupportedOperationException ° 


Map getServletRegistrations() 


该 方法 返回 ServletRegistration + 4% map， 由 名 称 作 为 键 并 对 应 着 注册 到 ServletContext 
的 所 有 Servlet。 如 果 没 有 Servlet 注册 到 ServletContext 则 返回 一 个 空 的 map。 返 回 的 Map 
包括 所 有 声明 和 注解 的 Servlet 对 应 的 ServletRegistration 对 象 ， 也 包括 那些 使 用 addServlet 
方法 添加 的 所 有 Servlet 对 于 的 ServletRegistration 对 象 。 返 回 的 Map 的 任何 改变 不 影响 
ServletContext。 如 果 ServletContext 传 到 了 ServletContextListener 的 contextlnitialized 7 
法 ， 但 该 ServletContextListener 即 没 有 在 web.xml 或 web-fragment.xml 中 声明 也 没有 使 用 
javax.servlet.annotation.WebListener 注解 ， 则 必须 抛 出 UnsupportedOperationException ° 


编程 式 添 加 和 配置 Filter 


addFilter(String filterName, String className) 

该 方法 允许 应 用 以 编程 方式 声明 一 个 Filter。 它 添加 以 给 定 的 名 称 和 class 名 称 的 Filter 到 web 
addFilter(String filterName, Filter filter) 

该 方法 允许 应 用 以 编程 方式 声明 一 个 Filter。 它 添加 以 给 定 的 名 称 和 filter 实例 的 Filter 到 web 
addFilter(String filterName, Class <? extends Filter> 


filterClass) 


该 方法 允许 应 用 以 编程 方式 声明 一 个 Filter。 它 添加 以 给 定 的 名 称 和 filter 类 的 一 个 实例 的 
Filter 到 web 应 用 。 


T createFilter(Class clazz) 
该 方法 实例 化 一 个 给 定 的 Filter class， 该 方法 必须 支持 适用 于 Filter 的 所 有 注解 。 


返回 的 Filter 实例 通过 调用 上 边 定义 的 addServlet(String, Filtem) 注 册 到 ServletContext 之 
前 ， 可 以 进行 进一步 的 定制 。 给 定 的 Filter 类 必须 定义 一 个 用 于 实例 化 的 空 参 构造 器 。 


FilterRegistration getFilterRegistration(String filterName) 


该 方法 返回 与 指定 名 字 的 Filter 相关 的 FilterRegistration， 或 者 如 果 没 有 该 名 字 的 
FilterRegistration 则 返回 null。 如 果 ServletContext 传 到 了 ServietContextListener 的 
contextlnitialized 方法 ， 但 该 ServletContextListener 即 没 有 在 web.xml 或 web-fragment.xml 
中 声明 也 没有 使 用 javax.servlet.annotation.WebListener 注解 ， 则 必须 抛 出 
UnsupportedOperationException ° 


Map getFilterRegistrations() 


该 方法 返回 FilterRegistration + #4) map， 由 名 称 作为 键 并 对 应 着 注册 到 ServletContext 的 
所 有 Filter。 如 果 没 有 Filter 注册 到 ServletContext 则 返回 一 个 空 的 Map。 返 回 的 Map 包括 所 
有 声明 和 注解 的 Filter 对 应 的 FilterRegistration 对 象 ， 也 包括 那些 使 用 addFilter 方法 添加 的 
所 有 Servlet 对 于 的 ServletRegistration 对 象 。 返 回 的 Map 的 任何 改变 不 影响 
ServletContext。 如 果 ServletContext 传 到 了 ServletContextListener 的 contextlnitialized 7 
法 ， 但 该 ServletContextListener 即 没 有 在 web.xml 或 web-fragment.xml 中 声明 也 没有 使 用 
javax.servlet.annotation.WebListener 注解 ， 则 必须 抛 出 UnsupportedOperationException ° 


编程 式 添 如 和 配置 Listener 


void addListener(String className) 


42 ServletContext 添加 指定 class 名 称 的 监听 器 。ServletContext 将 使 用 由 与 应 用 关联 的 
classloader 装载 加 载 该 给 定名 称 的 class， 且 它们 必须 实现 一 个 或 多 个 以 下 接口 : 


e javax.serviet.ServietContextAttributeListener 
e javax.serviet.ServietRequestListener 

e javax.serviet.ServietRequestAttributeListener 
e javax.serviet.http.HttpSessionListener 

e javax.serviet.http.HttpSessionAttributeListener 
e javax.serviet.http.HttpSessionldListener 


如 果 ServietContext 传 到 了 ServietContainerlnitializer 的 onStartup 方法 ， 则 给 定名 字 的 类 可 
以 实现 除 上 面 列 出 的 接口 之 外 的 javax.servlet.ServletContextListener。 作 为 该 方法 调用 的 一 
部 分 ， 容 器 必须 装载 指定 类 名 的 class， 以 确保 其 实现 了 所 需 的 接口 之 一 。 如 果 给 定名 字 的 类 


实现 了 一 个 监听 器 接口 ， 则 其 调用 顺序 和 声明 顺序 是 一 样 的 ， 换 句 话 说， 如 果 它 实现 了 
javax.servlet.ServletRequestListener 或 javax.servlet.http.HttpSessionListener， 那 么 新 的 监 
听 器 将 被 添加 到 该 接口 的 有 序 监听 器 列表 的 末尾 。 


void addListener(T t) 


往 ServletContext 添加 一 个 给 定 的 监听 器 。 给 定 的 监听 器 实例 必须 实现 一 个 或 多 个 如 下 接 
a: 


e javax.serviet.ServietContextAttributeListener 
e javax.serviet.ServietRequestListener 

e javax.serviet.ServietRequestAttributeListener 
e javax.serviet.http.HttpSessionListener 

e javax.serviet.http.HttpSessionAttributeListener 
e javax.serviet.http.HttpSessionldListener 


如 果 ServietContext 传 到 了 ServietContainerlnitializer 的 onStartup 方法 ， 则 给 定 的 监听 器 

例 可 以 实现 除 上 面 列 出 的 接口 之 外 的 javax.servlet.ServletContextListener ° fete 定 的 a 
器 实例 实现 了 一 个 监听 器 接口 ， 则 其 调用 顺序 和 声明 顺序 是 一 样 的 ， 换 句 话 说， 如果 它 实现 
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监听 器 将 被 添加 到 该 接口 的 有 序 监 听 器 列表 的 末尾 。 


void addListener(Class <? extends EventListener> 
listenerClass) 


4% ServletContext 添加 指定 class 类 型 的 监听 器 。 给 定 的 监听 器 类 必须 实现 是 一 个 或 多 个 如 
下 接口 : 


e javax.Servlet.ServletContextAttributeListener 


javax.serviet.ServietRequestListener 


javax.serviet.ServietRequestAttributeListener 
e javax.serviet.http.HttpSessionListener 

e javax.serviet.http.HttpSessionAttributeListener 
e javax.serviet.http.HttpSessionldListener 


如 果 ServietContext 传 到 了 ServietContainerlnitializer 的 onStartup 方法 ， 则 给 定 的 监听 器 类 
可 以 实现 除 上 面 列 出 的 接口 之 外 的 javax.servlet.ServletContextListener。 如 果 给 定 的 监听 器 
类 实现 了 一 个 监听 器 接口 ， 则 其 调用 顺序 和 声明 顺序 是 一 样 的 ， 换 名 话说， 如 果 它 实现 了 
javax.servlet.ServietRequestListener 或 javax.servlet.http.HttpSessionListener， 那 么 新 的 监 
听 器 将 被 添加 到 该 接口 的 有 序 监听 器 列表 的 末尾 。 


void createListener(Class clazz) 


该 方法 实例 化 给 定 的 EventListener 类 。 指 定 的 EventListener 类 必须 实现 至 少 一 个 如 下 接 
as 


e javax.serviet.ServietContextAttributeListener 
e javax.serviet.ServietRequestListener 


javax.serviet.ServietRequestAttributeListener 


javax.servlet.http.HttpSessionListener 
e javax.servlet.http.HttpSessionAttributeListener 
e javax.servlet.http.HttpSessionldListener 


该 方法 必须 支持 该 规范 定义 的 适用 于 如 上 接口 的 所 有 注解 。 返 回 的 EventListener 实例 可 以 在 
通过 调用 addListener(T t) 注册 到 ServletContext 之 前 进行 进一步 的 定制 。 给 定 的 
EventListener 必须 定义 一 个 用 于 实例 化 的 空 参 构 造 器 。 


用 于 编程 式 添加 Servlet ` Filter 和 Listener 的 注解 处 理 需 求 


除了 需要 一 个 实例 的 addServiet 之 外 ， 当 使 用 编程 式 API 添 加 Servlet 或 创建 Servlet 时 ， 以 下 
类 中 的 有 关 的 注解 必须 被 内 省 且 其 定义 的 元 数据 必须 被 使 用 ， 除 非 它 被 
ServietRegistration.Dynamic / ServletRegistration #18 Fl APIR s T o 


@ServletSecurity ` @RunAs ` @DeclareRoles ` @MultipartConfig ° 


对 于 Filter 和 Listener 来 说 ， 不 需要 使 用 注解 来 内 省 。 除了 通过 需要 一 个 实例 的 方法 添加 的 
那些 组 件 ， 编 程式 添加 或 创建 的 所 有 组 件 (Servlet，Filter 和 Listener) 上 的 资源 注入 ， 只 有 当 
组 件 是 一 个 CDI Managed Bean 时 才 被 支持 。 进 一 步 了 解 更 多 细节 请 参考 15.5.15，“JavaEE 
要 求 的 上 下 文 和 依赖 注入 ”。 


ETE 


servlet 可 以 通过 名 字 将 对 象 属性 绑 定 到 上 下 文 。 同 一 个 Web 应 用 内 的 其 他 任何 servlet 都 可 
以 使 用 绑 定 到 上 下 文 的 任意 属性 。 以 下 ServletContext 接口 中 的 方法 允许 访问 此 功能 : 


setAttribute 
getAttribute 
getAttributeNames 


removeAttribute 


分 布 式 容 器 中 的 上 下 文 属性 


在 JVM 中 创建 的 上 下 文 属性 是 本 地 的 ， 这 可 以 防止 从 一 个 分 布 式 容器 的 共享 内 存 存储 中 获取 

ServietContext 属性 。 当 需要 在 运行 在 分 布 式 环境 的 Servlet 之 间 共 享 信息 时 ， 该 信息 应 该 被 

放 到 会 话 中 (请 看 第 7 章 ，" 会 话 ") ， 或 存储 到 数据 库 ， 或 者 设置 到 Enterprise JavaBeans ™ 
(企业 级 JavaBean) 组 件 。 


ServletContext 接口 提供 了 直接 访问 Web 应 用 中 仅 是 静态 内 容 层 次 结构 的 文件 的 方法 ， 包 括 
HTML > GIF 和 JPEG 文件 : 


e getResource 
e getResourceAsStream 


getResource 和 getResourceAsStream 方法 需要 一 个 以 “1 开头 的 String 作为 参数 ， 给 定 的 
资源 路 径 是 相对 于 上 下 文 的 根 ， 或 者 相对 于 web 应 用 的 WEB-INF/lib 目录 下 的 JAR 文件 中 的 
META-INF/resources 目录 。 这 两 个 方法 首先 根据 请 求 的 资源 查找 web 应 用 上 下 文 的 根 ， 然 
后 查找 所 有 WEB-INF/lib 目录 下 的 JAR 文件 。 查 找 WEB-INF/lib 目录 中 JAR 文 件 的 顺序 是 不 
确定 的 。 这 种 层次 结构 的 文件 可 以 存在 于 服务 器 的 文件 系统 ，Web 应 用 的 归档 文件 ， 和 远程 服 
务 器 ， 或 在 其 他 位 置 。 


这 两 个 方法 不 能 用 于 获取 动态 内 容 。 例 如 ， 在 支持 JavaServer Pages™ 规 范 的 容器 中 ， 如 
getResource("/index.jsp") 形式 的 方法 调用 将 返回 ISP 源码 而 不 是 处 理 后 的 输出 。 请 看 第 9 

章 ，“ 分 发 请 求 "获取 更 多 关于 动态 内 容 的 信息 。 可 以 使 用 getResourcePaths(String path) 方 
法 访问 Web 应 用 中 的 资源 的 完整 列表 。 该 方法 的 语义 的 全 部 细节 可 以 从 本 规范 的 API 文档 中 
找到 。 


多 主机 和 Servlet 上 下 文 


Web 服务 器 可 以 支持 多 个 逻辑 主机 共享 一 个 服务 器 P 地址。 有时， 这 种 能 力 被 称 为 “虚拟 主 
机 ”。 这 种 情况 下 ， 每 一 个 逻辑 主机 必须 有 它 自己 的 servlet 上 下 文 或 一 组 servlet LFX ° 
servlet 上 下 文 不 会 在 虚拟 主机 之 间 共 享 。 


ServietContext 接口 的 getVirtualServerName 方法 允许 访问 ServletContext 部 署 在 的 逻辑 主 
机 的 配置 名 字 。 该 方法 必须 对 所 有 部 署 在 逻辑 主机 上 的 所 有 servlet 上 下 文 返 回 同一 个 名 字 。 
且 该 方法 返回 的 名 字 必 须 是 明确 的 、 每 个 逻辑 主机 稳定 的 、 和 适合 用 于 关联 服务 器 配置 信息 
和 逻辑 主机 。 


重 载 注意 事项 


尽管 Container Provider (容器 供应 商 ) 不 需要 实现 类 的 重 加 载 模式 以 便 易 于 开发 ， 但 是 任何 此 
类 的 实现 必须 确保 所 有 servlet 及 它们 使 用 的 类 〈Servlet 使 用 的 系统 类 异常 可 能 使 用 的 是 一 个 
不 同 的 class loader) 在 一 个 单独 的 class loader 范围 内 被 加 载 。 为 了 保证 应 用 像 开发 人 员 预 
期 的 那样 工作 ， 该 要 求 是 必须 的 。 作 为 一 个 开发 辅助 ， 容 器 应 支持 到 会 话 绑 定 到 的 监听 器 的 
完整 通知 语义 以 用 于 当 class 重 加 载 时 会 话 终结 的 监控 。 


之 前 几 代 的 容器 创建 新 的 class loader 来 加 载 servlet， 且 与 用 于 加 载 在 servlet 上 下 文中 使 用 
的 其 他 servlet 或 类 的 class loader 是 完全 不 同 的 。 这 可 能 导致 servlet 上 下 文中 的 对 象 引 用 指 
向 意 想 不 到 的 类 或 对 象 ， 并 引起 意 想不到 的 行为 。 为 了 防止 因 创建 新 的 class loader 所 引起 的 
问题 ， 该 要 求 是 必须 的 。 


临时 工作 目录 


每 一 个 servlet 上 下 文 都 需要 一 个 临时 的 存储 目录 。Servlet 容器 必须 为 每 一 个 servlet LFX 
提供 一 个 私有 的 临时 目录 ， 并 将 通过 javax.servlet.context.tempdir 上 下 文 属性 使 其 可 用 ， 关 
联 该 属性 的 对 象 必须 是 java.io.File 类 型 。 


该 要 求 公认 为 在 多 个 servlet 引擎 实现 中 提供 一 个 通用 的 便利 。 当 servet 容器 重启 时 ， 它 不 
需要 去 保持 临时 目录 中 的 内 容 ， 但 必须 确保 一 个 servlet 上 下 文 的 临时 目录 中 的 内 容 对 运行 在 
同一 个 servlet 容器 的 其 他 Web 应 用 的 上 下 文 不 可 见 。 


响应 


mo Pore 返回 到 客户 端的 所 有 信息 。 在 HTTP 协议 中 ， 从 服务 器 传输 到 客户 
端的 信息 通过 HTTP 头 信息 或 响应 的 消息 体 。 


缓冲 


出 于 性 能 的 考虑 ，servlet 容器 允许 (但 不 要 求 ) 缓存 输出 到 客户 端的 内 容 。 一 般 的 ， 服 务 器 
是 默认 执行 缓存 ， 但 应 该 允许 servlet 来 指定 缓存 参数 。 


下 面 是 ServletResponse 接口 允许 servlet 来 访问 和 设置 缓存 信息 的 方法 | 


e getBufferSize 
e setBufferSize 
e isCommitted 
e reset 

e resetBuffer 
e flushBuffer 


X € servlet 使 用 的 是 一 个 ServletOutputStream 还 是 一 个 Writer > ServletResponse 接口 提 

供 的 这 些 方法 允许 执行 缓冲 操作 。 getBufferSize 方法 返回 使 用 的 底层 缓冲 区 大 小 。 如 果 没 有 
使 用 缓冲 ， 该 方法 必须 返回 一 个 int 值 0。 Servlet 可 以 请 求 setBufferSize 方法 设置 一 个 最 佳 
的 缓冲 大 小 。 不 一 定 分 配 servlet 请 求 大 小 的 缓冲 区 ， 但 至 少 与 请 求 的 大 小 一 样 大 。 这 人 允许 容 
器 重用 一 组 固定 大 小 的 缓冲 区 ， 如 果 合 适 ， 可 以 提供 一 个 比 请 求 时 更 大 的 缓冲 区 。 该 方法 必 

须 在 使 用 ServletOutputStream 或 Writer 写 任何 内 容 之 前 调用 。 如 果 已 经 写 了 内 容 或 响应 对 

象 已 经 提交 ， 则 该 方法 必须 抛 出 llegalStateException 。 


isCommitted 方法 返回 一 个 表示 是 否 有 任何 响应 字 节 已 经 返回 到 客户 端的 boolean 值 。 
flushBuffer 方法 强制 刷 出 缓冲 区 的 内 容 到 客户 端 。 当 响应 没有 提交 时 ，reset 方 法 清空 缓冲 区 
的 数据 。 头 信息 ， 状 态 码 和 在 调用 reset 之 前 serviet 调用 getWriter 或 getOutputStream 设 
置 的 状态 也 必须 被 清空 。 如 果 响 应 没有 被 提交 ，resetBuffer 方法 将 清空 缓冲 区 中 的 内 容 ， 但 
不 清空 请 求 头 和 状态 码 。 


如 果 响 应 已 经 提交 并 且 reset 或 resetBuffer 方法 已 被 调用 ， 则 必须 抛 出 
llegalStateException， 响 应 及 它 关 联 的 缓冲 区 将 保持 不 变 。 


当 使 用 缓冲 区 时 ， 容 器 必须 立即 刷 出 填 满 的 缓冲 区 内 容 到 客户 端 。 如 果 这 是 最 早 发 送 到 客户 
端的 数据 ， 且 认为 响应 被 提交 了 。 


头 
N 


servlet 可 以 通过 下 面 HttpServletResponse 接口 的 方法 来 设置 HTTP 响应 头 : 


e SetHeader 
e addHeader 


setHeader 方法 通过 给 定 的 名 字 和 值 来 设置 头 。 前 面 的 头 会 被 后 来 的 新 的 头 替 换 。 如 果 已 经 存 
在 同名 的 头 集合 的 值 ， 集 合 中 的 值 会 被 清空 并 用 新 的 值 蔡 换 。 


addHeader 方法 使 用 给 定 的 名 字 添 加 一 个 头 值 到 集合 。 如 果 没 有 头 与 给 定 的 名 字 关 联 ， 则 创 
建 一 个 新 的 集合 。 


头 可 能 包含 表示 int 或 Date 对 象 的 数据 。 以 下 HttpServletResponse 接 口 提供 的 便利 方法 允 
许 servlet 对 适当 的 数据 类 型 用 正确 的 格式 设置 一 个 头 : 


e setintHeader 
e setDateHeader 
e addlntHeader 
e addDateHeader 


为 了 成 功 的 传 回 给 客户 端 ， 头 必须 在 响应 提交 前 设置 。 响 应 提交 后 的 头 设 置 将 被 servlet 容器 
忽略 o 


servlet 程序 员 负 责 保 证 为 servlet 生成 的 内 容 设置 合适 的 响应 对 象 的 Content-Type = * HTTP 
M AŠPRKEKE HTP a PREM oS soviet ESA RARI RAD + verviet 
容器 也 不 能 设置 默认 的 内 容 类 型 。 


建议 容器 使 用 X-Powered-By HTTP 头 公 布 它 的 实 aes 字段 值 应 考虑 一 个 或 多 个 实现 类 
型 ， 如 "Servlet/3.1"。 容 器 应 该 可 以 配置 来 隐藏 该 头 。 可 选 的 容器 补充 的 信息 和 底层 Java 平 
台 可 以 被 放 在 括号 内 并 添加 到 实现 类 型 之 后 。 


X-Powered-By: Servlet/3.1 
X-Powered-By: Servlet/3.1 JSP/2.3 (GlassFish Server Open Source 
Edition 4.0 Java/Oracle Corporation/1.7) 


非 阻塞 IO 


非 阻塞 IO 仅 对 在 Servlet 和 Filter 〈2.3.3.3 节 定义 的 ，" 异 步 处 理 ") 中 的 异步 请 求 处 理 和 升级 
处 理 (2.3.3.5 节 定义 的 ， “升级 处 理 ”) 有 效 。 否则 ， 当 调用 
ServletlnputStream.setReadListener 或 ServletOutputStream.setWriteListener 方法 时 将 抛 出 
lllegalStateException。 为 了 支持 在 Servlet 容器 中 的 非 阻 塞 写 ， 除 了 在 3.7 节 描述 的 “ 非 阻塞 
IO" 对 ServietRequest 做 的 更 改 之 外 ， 下 面 做 出 的 更 改 以 便于 处 理 响应 相关 的 类 /接口 。 


WriteListener 提供 了 如 下 适用 于 容器 调用 的 回调 方法 。 


e WriteListener 

o void onWritePossible(). 当 一 个 WriteListener 注册 到 ServletOutputStream 时 ， 当 可 
以 写 数 据 时 该 方法 将 被 容器 首次 调用 。 当 且 仅 当下 边 描述 的 ServletOutputStream 的 
isReady 方法 返回 false， 容 器 随后 将 调用 该 方法 。 

o onError(Throwable t). 当 处 理 响应 过 程 中 出 现 错误 时 回调 。 除了 WriteListener 外 ， 
还 有 如 下 方法 被 添加 到 ServletOutputStream 类 并 允许 开发 人 员 运 行 时 检查 是 否 可 以 

e ServietOutputStream 

o boolean isReady(). 如 果 往 ServietOutputStream 号 会 成 功 ， 则 该 方法 返回 true > # 
他 情况 会 返回 false。 如 果 该 方法 返回 true， 可 以 在 ServletOutputStream 上 执行 写 
操作 。 如 果 没 有 后 续 的 数据 能 写 到 ServletOutputStream， 那 么 直到 底层 的 数据 被 刷 
出 之 前 该 方法 将 一 直 返 回 false。 且 在 此 时 容器 将 调用 WriteListener 的 
onWritePossible 方法 。 随 后 调用 该 方法 将 返回 true。 

o void setWriteListener(WriteListener listener). 关联 WriteListener 和 当 且 的 
ServletOutputStream ， 当 ServletOutputStream 可 以 写 入 数据 时 容器 会 调用 
WriteListener 的 回调 方法 。 注 册 了 WriteListener 将 开始 非 阻塞 |O。 此 时 再 切换 到 传 
统 的 阻塞 IO 是 非法 的 。 


容器 必须 线程 安全 的 访问 WriteListener 中 的 方法 。 


kk > 
简便 方法 
HttpServletResponse 提 供 了 如 下 简便 方法 : 


e sendRedirect 

e sendError * sendRedirect 方法 将 设置 适当 的 头 和 内 容 体 将 客户 端 重 定向 到 另 一 个 地 址 。 
使 用 相对 URL 路 径 调用 该 方法 是 合法 的 ， 但 是 底层 的 容器 必须 将 传 回 到 客户 端的 相对 地 
址 转换 为 全 路 径 URL。 无 论 出 于 什么 原因 ， 如 果 给 定 的 URL 是 不 完整 的 ， 且 不 能 转换 为 
一 个 有 效 的 URL， 那 么 该 方法 必须 抛 出 legalArgumentException 。 


sendError 方法 将 设置 适当 的 头 和 内 容 体 用 于 返回 给 客户 端 返回 错误 消息 。 可 以 sendError + 
法 提供 一 个 可 选 的 String 参数 用 于 指定 错误 的 内 容 体 。 


如 果 响 应 已 经 提交 并 终止 ， 这 两 个 方法 将 对 提交 的 响应 产生 负 作 用 。 这 两 个 方法 调用 后 
servlet 将 不 会 产生 到 客户 端的 后 续 的 输出 。 这 两 个 方法 调用 后 如 果 有 数据 继续 写 到 响应 ， 这 
些 数据 被 忽略 。 如 果 数 据 已 经 写 到 响应 的 旨 冲 区 ， 但 没有 返回 到 客户 端 〈 例 如 ， 响 应 没有 提 
X) ， 则 响应 缓冲 区 中 的 数据 必须 被 清空 并 使 用 这 两 个 方法 设置 的 数据 替换 。 如 果 响 应 已 提 
交 ， 这 两 个 方法 必须 抛 出 lllegalStateException。 


国际 化 


Servlet 应 设置 响应 的 locale 和 字符 集 。 使 用 ServletResponse.setLocale 方法 设置 locale。 该 
方法 可 以 重复 的 调用 ; 但 响应 被 提交 后 调用 该 方法 不 会 产生 任何 作用 。 如 果 在 页 面 被 提交 之 
前 servlet 没有 设置 locale， 容 器 的 默认 locale 将 用 来 确定 响应 的 locale， 但 是 没有 制定 与 客 
户 端 通信 的 规范 ， 例 如 使 用 HTTP 情况 下 的 Content-Language = ° 


<locale-encoding-mapping-list> 
<locale-encoding-mapping> 
<locale>ja</locale> 
<encoding>Shift_JIS</encoding> 
</locale-encoding-mapping> 
</locale-encoding-mapping-list> 


如 果 该 元 素 不 存在 或 没有 提供 映射 ，setLocale 使 用 容器 依赖 的 映射 。 
setCharacterEncoding，setContentType 和 setLocale 方法 可 以 被 重复 的 调用 来 改变 字符 编 
码 。 如 果 在 servlet 响应 的 getWriter 方法 已 经 调用 之 后 或 响应 被 提交 之 后 ， 调 用 相关 方法 设 
置 字符 编码 将 没有 任何 作用 。 只 有 当 给 定 的 上 下 文 类 型 字符 串 提 供 了 一 个 charset 属性 值 ， 调 
用 setContentType 可 以 设置 字符 编码 。 只 有 当 既 没有 调用 setCharacterEncoding 也 没有 调 
用 setContentType 去 设置 字符 编码 之 前 调用 setLocale 才 可 以 设置 字符 编码 。 


在 ServietResponse 接口 的 getWriter 方法 被 调用 或 响应 被 提交 之 前 ， 如 果 serviet 没有 指定 
字符 编码 ， 默 认 使 用 ISO-8859-1 ° 


如 果 使 用 的 协议 提供 了 一 种 这 样 做 的 方式 ， 容 器 必须 传递 servlet 响应 的 writer 使 用 的 locale 
和 字符 编码 到 客户 端 。 使 用 HTTP 的 情况 下 ，locale 可 以 使 用 Content-Language 头 传递 ， 字 
符 编 码 可 以 作为 用 于 指定 文本 媒体 类 型 的 Content-Type 头 的 一 部 分 传递 。 注 意 ， 如 果 没 有 指 
定 上 下 文 类 型 ， 字 符 编码 不 能 通过 HTTP 头 传递 ; 但 是 仍 使 用 它 来 编码 通过 Servlet 响应 的 
writer 写 的 文本 。 


结束 响应 对 象 


当 响 应 被 关闭 时 ， 容 器 必须 立即 刷 出 响应 缓冲 区 中 的 所 有 剩余 的 内 容 到 客户 端 。 以 下 事件 表 
明 servlet 满足 了 请 求 且 响 应 对 象 即 将 关闭 : 


servlet 的 service 方法 终止 。 

e 响应 的 setContentLength 或 setContentLengthLong 方法 指定 了 大 于 零 的 内 容量 ， 且 已 
经 写 入 到 响应 。 

e sendError 方法 已 调用 。5.6 

e sendRedirect 方法 已 调用 。 

e AsyncContext 的 complete 方法 已 调用 


响应 对 象 的 生命 周期 


每 个 响应 对 象 是 只 有 当 在 servlet 的 service 方法 的 范围 内 或 在 filter 的 doFilter 方法 范围 内 是 
有 效 的 ， 除 非 该 组 件 关联 的 请 求 对 象 已 经 开启 异步 处 理 。 如 果 相 关 的 请 求 已 经 启动 异步 处 
理 ， 那 么 直到 AsyncContext 的 complete 方法 被 调用 ， 请 求 对 象 一 直 有 效 。 为 了 避免 响应 对 
象 创建 的 性 能 开销 ， 容 器 通常 回收 响应 对 象 。 在 相关 的 请 求 的 startAsync 还 没有 调用 时 ， 开 
发 人 员 必 须 意 识 到 保持 到 响应 对 象 引 用 ， 超 出 之 上 描述 的 范围 可 能 导致 不 确定 的 行为 。 


Filter (过 滤器 ) 是 Java 组 件 ， 人 允许 运行 过 程 中 改变 进入 资源 的 请 求 和 资源 返回 的 响应 中 的 有 
效 负 载 和 头 信息 Ww 

Java Servlet API 类 和 方法 提供 了 一 种 轻 量 级 的 框架 用 于 过 滤 动 态 和 静态 内 容 。 还 描述 了 如 何 
在 Web 应 用 配置 filter， 以 及 它们 实现 的 约定 和 语义 。 


网 上 提供 了 servlet 过 滤器 的 AP| 文 档 。 过 滤器 的 配置 语法 在 第 14 章 的 “部 署 描述 符 " 中 的 部 署 
当 述 符 模式 部 分 给 出 。 当 阅读 本章 时 ， 读 者 应 该 是 将 这 些 资源 作为 参考 。 


什么 


过 滤 
常 不 
来 自 


过 滤 


日 ` 4 
过 滤器 


器 是 一 种 代码 重用 的 技术 ， 它 可 以 转换 HTTP 请 求 的 内 容 ， 响 应 ， 及 头 信 息 。 过 滤器 通 
产生 响应 或 像 Servlet 那样 对 请 求 作 出 响应 ， 而 是 修改 或 调整 到 资源 的 请 求 ， 修 改 或 调整 
资源 的 响应 。 


器 可 以 作用 于 动态 或 静态 内 容 。 这 章 说 的 动态 和 静态 内 容 指 的 是 Web 资源 。 


供 开发 人 员 使 用 的 过 滤器 功能 有 如 下 几 种 类 型 : 


在 执行 请 求 之 前 访问 资源 。 

在 执行 请 求 之 前 处 理 资 源 的 请 求 。 

用 请 求 对 象 的 自 定 义 版 本 包装 请 求 对 请 求 的 header 和 数据 进行 修改 。 
用 响应 对 象 的 自 定 义 版 本 包装 响应 对 响应 的 header 和 数据 进行 修 
拦截 资源 调用 之 后 的 调用 。 

作用 在 一 个 Servlet， 一 组 Servlet， 或 静态 内 容 上 的 零 个 ， 一 个 或 多 个 拦截 器 按 指定 的 顺 
序 执行 


> 
\ 
= 


过 滤器 组 件 示 例 


Authentication filters /用 户 身 份 验证 过 滤器 

Logging and auditing filters /日 志 记 录 和 与 审计 过 滤器 

Image conversion filters // 图 片 转换 过 滤器 

Data compression filters /数据 压缩 过 滤器 

Encryption filters // 加 密 过 滤器 

Tokenizing filters // 分 词 过 滤 

Filters that trigger resource access events // 触 发 资源 访问 事件 过 滤 
XSL/T filters that transform XML content 

MIME-type chain filters //MIME-TYPE 链 过 滤器 

Caching filters /缓存 过 滤器 


主要 概念 


本 章 描述 了 过 滤器 模型 的 主要 概念 。 


应 用 开发 人 员 通 过 实现 javax.servlet.Filter 接口 并 提供 一 个 公共 的 空 参 构造 器 来 创建 过 滤器 。 
该 类 及 构建 Web 应 用 的 静态 资源 和 servlet 打包 在 Web 应 用 归档 文件 中 。Filter 在 部 署 描述 符 
中 通过 <filter> 元 素 声 明 。 一 个 过 滤器 或 一 组 过 滤器 可 以 通过 在 部 署 描述 符 中 定义 <filter- 
mapping> 来 为 调用 配置 。 可 以 使 用 servlet 的 逻辑 视图 名 把 过 滤器 映射 到 一 个 特定 的 servlet > 
或 者 使 用 URL 模式 把 一 组 servlet 和 静态 内 容 资 源 映 射 到 过 滤器 。 


过 滤器 生命 周期 


在 Web 应 用 部 署 之 后 ， 在 请 求 导 致 容器 访问 Web 资源 之 前 ， 容 器 必须 找到 过 滤器 列表 并 按 

照 如 上 所 述 的 应 用 到 Web 资源 。 容 器 必须 确保 它 为 过 Oa is 

当 类 器 ,并 调用 其 init(FilterConfig config) 方法 。 过 滤器 可 能 会 抛 出 一 个 异常 ,以 表明 它 

不 能 正常 运转 。 een 类 pres sere ， 容 器 可 以 检查 异常 的 isPermanent 
先 择 稍 候 重 试 过 


N <filter> 在 每 个 JVM 的 容器 中 仅 实 例 化 一 个 实例 。 容 器 提供 了 
声明 在 过 滤器 的 部 署 描述 符 的 过 滤器 config ( 译 者 注 : FilterConfig) ， 对 Web 应 用 的 
ServletContext 的 引用 ， 2 o 


当 容 器 接收 到 传 入 的 请 求 时 ， 它 将 获取 列表 中 的 第 一 个 过 滤器 并 调用 doFilter 方法 ， ho 
ServletRequest 和 ServletResponse， 和 一 个 它 将 使 用 的 FilterChain 4 #094] Alo 过 滤器 的 
doFilter 方法 通常 会 被 实现 为 如 下 或 如 下 形式 的 子 集 : 


1. 该 方法 检查 请 求 的 头 

2， 该 方法 可 以 用 自 定义 的 ServletRequest 或 HttpServletRequest 实现 包装 请 求 对 象 为 了 修 
改 请 求 的 头 或 数据 。 

3. 该 方法 可 以 用 自 定义 的 ServletResponse 或 HttpServletResponse 实 现 包 装 传 入 doFilter 
方法 的 响应 对 象 用 于 修改 响应 的 头 或 数据 。 

4. 该 过 滤器 可 以 调用 过 滤器 链 中 的 下 一 个 实体 。 下 一 个 实体 可 能 是 另 一 个 过 滤器 ， 或 者 如 
果 当 前 调用 的 过 滤器 是 该 过 滤器 链 配 置 在 部 署 描述 符 中 的 最 后 一 个 过 滤器 ， 下 一 个 实体 
是 目标 Web 资 源 。 调 用 FilterChain 对 象 的 doFilter 方 法 将 影响 下 一 个 实体 的 调用 ， 且 传 入 
的 它 被 调用 时 请 求 和 响应 ， 或 传 入 它 可 能 已 经 创建 的 包装 版 本 。 由 容器 提供 的 过 滤器 链 
SARE T a 实现 ， alias: mer e eas 它 的 doFilter 方 法 ， 传 入 

适当 的 请 求 和 响应 对 象 。 另 外 ， 过 滤器 链 可 以 通过 不 调用 下 一 个 实体 来 阻止 请 求 ， 离 开 
过 滤器 负责 填充 响应 对 象 。 service 方法 必须 和 应 用 到 servlet 的 所 有 过 滤器 运行 在 同一 
个 线程 中 。 
5， 过 滤器 链 中 的 下 一 个 过 滤器 调用 之 后 ， 过 滤器 可 能 检查 响应 的 头 


6. 另外 ， 过 滤器 可 能 抛 出 一 个 异常 以 表示 处 理 过 程 中 出 错 了 。 如 果 过 滤器 在 doFilter 处 理 过 
程 中 抛 出 UnavailableException ， 容 器 必须 停止 处 理 剩 下 的 过 滤器 链 。 如 果 异 常 没有 标 
识 为 永久 的 ， 它 或 许 选择 稍 候 重 试 整个 链 。 

7. 当 链 中 的 最 后 的 过 滤器 被 调用 ， 下 一 个 实体 访问 的 是 链 最 后 的 目标 servlet 或 资源 。 

8. 在 容器 能 把 服务 中 的 过 滤器 实例 移 除 之 前 ， 容 器 必须 先 调用 过 滤器 的 destroy 方法 以 便 过 
滤器 释放 资源 并 执行 其 他 的 清理 工作 。 


包装 请 求 和 响应 


过 滤器 的 核心 概念 是 包装 请 求 或 响应 ， 以 便 它 可 以 履 盖 行为 执行 过 滤 任务 。 在 这 个 模型 中 ， 
开发 人 员 不 仅 可 以 覆盖 请 求 和 响应 对 象 上 已 有 的 方法 ， 也 能 提供 新 的 API 以 适用 于 对 过 滤器 
链 中 剩 下 的 过 滤器 或 目标 web 资源 做 特殊 的 过 滤 任务 。 例 如 ， 开 发 人 员 可 能 希望 用 更 高 级 别 
的 输出 对 象 如 output stream 或 writer 来 扩展 响应 对 象 ， 如 允许 DOM 对 象 写 回 客户 端的 
API ° 


为 了 支持 这 种 风格 的 过 滤器 ， 容 器 必须 支持 如 下 要 求 。 当 过 滤器 调用 容器 的 过 滤器 链 实现 的 
doFilter 方法 时 ， 容 器 必须 确保 请 求 和 响应 对 象 传 到 过 滤器 链 中 的 下 一 个 实体 ， 或 如 果 过 滤器 
是 链 中 最 后 一 个 ， 将 传 入 目标 Web 资源 ， 且 与 调用 过 滤器 传 入 doFilter 方法 的 对 象 是 一 样 
的 。 


当 调 用 者 包装 请 求 或 响应 对 象 时 ， 对 包装 对 象 的 要 求 同 样 适用 于 从 servlet 或 过 滤器 到 
RequestDispatcher.forward 或 RequestDispatcher.include 的 调用 。 在 这 种 情况 下 ， 调 用 
servlet 看 到 的 请 求 和 响应 对 象 与 调用 servlet 或 过 滤器 传 入 的 包装 对 象 必 须 是 一 样 的 。 


过 滤器 环境 


Pak 述 符 中 的 <init-params> 元 素 把 一 组 初始 化 参数 关联 到 过 滤器 。 这 些 参数 的 名 
字 和 值 在 过 滤器 运行 期 间 可 以 使 用 过 滤器 的 FilterConfig 对 象 的 getlnitParameter 和 
en 方法 得 到 。 另 外 ，FilterConfig 提供 访问 Web 应 用 的 ServletContext 
用 于 加 载 资源 ， 记 录 日 志 ， 在 ServletContext 的 属性 列表 存储 状态 。 链 中 最 后 的 过 滤器 和 目 

标 servlet 或 资源 必须 执行 在 同一 个 调用 线程 。 


在 Web 应 用 中 配置 过 滤器 


过 滤器 可 以 通过 规范 的 第 8.1.2 节 “@WebFilter" 的 @WebFilter 注解 定义 或 者 在 部 署 描述 符 中 
使 用 <filter> 元 素 定义 。 在 这 个 元 素 中 ， 程 序 员 可 以 声明 如 下 内 容 : 


e filter-name: 用 于 映射 过 滤器 到 servlet 或 URL 
e filter-class: 由 容器 用 于 表示 过 滤器 类 型 
e init-params: 过 滤器 的 初始 化 参数 


程序 员 可 以 选择 性 的 指定 icon 图 标 ， 文 字 说 明 ， 和 工具 操作 显示 的 名 字 。 GRANA A NEH 
声明 实例 化 一 个 Java 类 实例 。 因 此 ， 如 果 开 发 人 员 对 同一 个 过 滤器 


述 符 中 定义 的 每 个 过 滤器 声 
类 声明 了 两 次 ， 则 容器 将 实例 化 两 个 相同 的 过 滤器 类 的 实例 。 


<filter> 
<filter-name>Image Filter</filter -name> 
<filter-class>com.acme.ImageServlet</filter-class> 
</filter> 


一 旦 在 部 署 描 述 符 中 声明 了 过 滤器 ， Ais 使 用 <filter-mapping> 定义 Web 应 用 中 的 
servlet 和 静 态 资 源 到 过 滤器 的 应 用 。 过 滤器 可 以 使 用 <servlet-name> 元 素 关联 到 一 个 
Servlet。 例 如 ， pets 代码 映射 和 Filter 


过 滤器 到 ImageServlet servlet : 


<filter-mapping> 
<filter-name>Image Filter</filter-name> 
<servlet -name>ImageServlet</servlet -name> 
</filter -mapping> 


过 滤器 可 以 使 用 <url-pattern> PAG AY) ZL JE 2 器 映射 关联 到 一 组 servlet 和 静态 SANE: 


<filter-mapping> 
<filter-name>Logging Filter</filter-name> 
<url-pattern>/*</url-pattern> 
</filter-mapping> 


在 这 里 ，Logging 过 滤器 应 用 到 Web 应 用 中 的 所 有 servlet 和 静态 资源 ， 因 为 每 一 个 请 求 的 
URI e/t URL 模式 。 


当 使 用 <url-pattern> 风格 配置 <filter-mapping> 元 素 ， 容 器 必须 使 用 定义 在 12 章 “上 映射 请 求 
到 Servlet" 中 的 路 径 映 射 规则 决定 <url-pattern> 是 否 匹 配 请 求 URI 。 


容器 使 用 的 用 于 构建 应 用 到 一 个 特定 请 求 URI 的 过 滤器 链 的 顺序 如 下 所 示 : 


首先 ， <url-pattern> 按照 在 部 署 描 述 符 中 的 出 现 顺 序 匹 配 过 滤器 映射 。 
2. dk Tk > <servlet-name> 按照 在 部 署 描述 符 中 的 出 现 顺 序 匹 配 过 滤器 映射 。 


bee 滤器 映射 同时 包含 了 <servlet-name> 和 <url-pattern> ， 容 器 必须 展开 过 滤器 映射 为 
器 映射 (每 一 个 <servlet-name> 和 <url- GaS 一 个 ) 2 保持 <servlet- 


name> 和 <url-pattern> 元 素 顺 序 。 例 如 ， 以 下 过 滤器 映射 : 


过 滤 
个 过 滤 


<filter -mapping> 
<filter-name>Multipe Mappings Filter</filter-name> 
<url-pattern>/foo/*</url-pattern> 
<servlet-name>Servlet1</servlet-name> 
<servlet-name>Servlet2</servlet-name> 
<url-pattern>/bar/*</url-pattern> 
</filter-mapping> 


等 价 于 


<filter-mapping> 
<filter-name>Multipe Mappings Filter</filter-name> 
<url-pattern>/foo/*</url-pattern> 
</filter-mapping> 
<filter -mapping> 
<filter-name>Multipe Mappings Filter</filter-name> 
<servlet -name>Servleti</servlet -name> 
</filter-mapping> 
<filter-mapping> 
<filter-name>Multipe Mappings Filter</filter-name> 
<servlet-name>Servlet2</servlet-name> 
</filter-mapping> 
<filter-mapping> 
<filter-name>Multipe Mappings Filter</filter-name> 
<url-pattern>/bar/*</url-pattern> 
</filter-mapping> 


关于 过 滤器 链 顺序 的 要 求 意味 着 容器 ， 当 接收 到 传 入 的 请 求 ， 按 照 如 下 方式 处 理 请 求 : 


e 按 “ 映 射 规则 ”识别 目标 Web 资源 。 

。 如 果 有 过 滤器 使 用 servlet name 匹配 到 具有 <serviet-name> 的 Web 资源 ， 容 器 以 声明 
在 部 署 描述 符 中 的 顺序 构建 过 滤器 链 。 该 链 中 的 最 后 一 个 过 滤器 ， 即 最 后 一 个 <servlet- 
name> 匹配 的 过 滤器 将 调用 目标 Web 资 源 。 

o. 如 果 有 过 滤器 使 用 <url- pattern> 匹配 且 该 <url-pattern> 按照 第 12.2 节 “映射 规则 ”中 的 
规则 匹配 请 求 的 URI， 容 器 容 ie 明 在 部 署 描述 符 中 的 顺序 构建 <url-pattern> 匹配 到 

的 过 滤器 链 。 该 链 中 的 最 后 一 个 过 滤器 是 在 部 署 描述 符 中 对 当前 请 求 URI 最 后 一 
个 <url-pattern> 匹配 的 过 滤器 。 a ap S <servlet-name> 匹配 的 链 
中 的 第 一 个 过 滤器 ， 或 如 果 没 有 ， 则 调用 目标 Web 资源 。 


a 


Web 容器 要 有 高 性 能 表现 ， 必 须 缓存 过 滤器 链 从 而 不 需要 根据 每 个 请 求 重 新 计算 它们 。 


滤器 和 RequestDispatcher 


Java Servlet 规范 自从 2.4 新 版 本 以 来 ， 能 够 在 请 求 分 派 器 forward() 和 include() 调用 情况 下 
配置 可 被 调用 的 过 滤器 。 


通过 在 部 署 描述 符 中 使 用 新 的 <dispatcher> 元 素 ， 开 发 人 员 可 以 为 filter-mapping 指定 是 否 想 
要 过 滤器 应 用 到 | 请 青 求 ， 4 


.请 求 直 接 来 自 客 户 端 。 可 以 由 一 个 带 有 REQUEST 444 <dispatcher> 元 素 ， 或 者 没有 任 

何 <dispatcher> 元 素来 表示 。 

2. 使 用 表示 匹配 <url-pattern> 或 <servlet-name> 的 Web 组 件 的 请 求 分 派 器 的 forward() 
调用 情况 下 处 理 请 求 。 可 以 由 一 个 带 有 FORWARD 值 的 <dispatcher> 元 素 表 示 。 

3. 使 用 表示 匹配 <url- pattern> 或 <servlet-name> 的 Web 组 件 的 请 求 分 派 器 的 include() 
调用 情况 下 处 理 请 求 。 可 以 由 一 个 带 有 INCLUDE 值 的 <dispatcher> 元 素 表示 。 

4. 使 用 “错误 处 理 " 指 定 的 错误 页 面 机 制 处 理 匹 配 <url-pattern> 的 错误 资源 的 请 求 。 可 以 由 
一 个 带 有 ERROR 4849 <dispatcher> 元 素 表 示 。 

5. 使 用 指定 的 “异步 处 理 " 中 的 异步 上 下 文 分 派 机 制 对 web 组 件 使 用 dispatch 调用 处 理 请 
求 。 可 以 由 一 个 带 有 ASYNC 值 的 <dispatcher> 元 素 表示 。 

6. 或 之 上 1，2，3，4 或 5 的 任何 组 合 。 


如 i 


<filter-mapping> 
<filter-name>Logging Filter</filter-name> 
<url-pattern>/products/*</url-pattern> 
</filter-mapping> 


客户 端 以 /products/... 开始 的 请 求 将 导致 Logging Filter 被 调用 ， 但 不 是 在 以 路 
径 /products/... 开始 的 请 求 分 派 器 调用 情况 下 。LoggingFilter 将 在 初始 请 求 分 派 和 恢复 请 求 
时 被 调用 。 如 下 代码 : 


<filter-mapping> 
<filter-name>Logging Filter</filter-name> 
<servlet-name>ProductServlet</servlet-name> 
<dispatcher>INCLUDE</dispatcher> 
</filter-mapping> 


客户 端 到 ProductServlet 的 请 求 将 不 会 导致 Logging Filter 被 调用 ， 且 也 不 会 在 请 求 分 派 器 
forward() 调用 到 ProductServlet 情况 时 ， 仅 在 以 ProductServlet 名 字 开 头 的 请 求 分 派 器 
include() 调用 时 被 调用 。 如 下 代码 : 


<filter-mapping> 
<filter-name>Logging Filter</filter-name> 
<url-pattern>/products/*</url-pattern> 
<dispatcher>FORWARD</dispatcher> 
<dispatcher>REQUEST</dispatcher> 

</filter -mapping> 


客户 端 以 /products/... 开始 的 请 求 ， 或 在 以 路 径 /products/... 开始 的 请 求 分 派 器 forward() 
调用 情况 时 ， 将 导致 Logging Filter 被 调用 。 


最 后 ， 如 下 代码 使 用 特殊 的 servlet ZF”: 


<filter-mapping> 
<filter-name>All Dispatch Filter</filter-name> 
<servlet-name>*</servlet-name> 
<dispatcher>FORWARD</dispatcher> 

</filter -mapping> 


在 按 名 字 或 按 路 径 获取 的 所 有 请 求 分 派 器 forward() 调用 时 该 代码 将 导致 All Dispatch Filter 被 
调用 。 


会 话 


超 文本 传输 协议 (HTTP) 被 设计 为 一 种 无 状态 协议 。 为 构建 有 效 的 Web 应 用 ， 使 来 自 一 个 
特定 的 客户 端的 请 求 彼 此 相关 联 是 必要 的 。 随 时 间 的 推移 ， 演 变 了 许多 会 话 跟 踪 机 制 ， 这 些 
机 制 直接 使 用 对 程序 员 而 言 是 困难 或 麻烦 的 。 


该 规范 定义 了 一 个 简单 的 HttpSession 接口 ， 允 许 servlet 容器 使 用 几 种 方法 来 跟踪 用 户 会 
话 ， 而 不 会 使 应 用 开发 人 员 陷 入 到 这 些 方法 的 细节 中 。 


会 话 跟 踪 机 制 


Cookie 
通过 HTTP cookie 的 会 话 跟 踪 是 最 常用 的 会 话 跟踪 机 制 ， 且 所 有 servlet 容器 都 应 该 支持 。 
器 向 客户 端 发 送 一 个 cookie， 客 户 端 后 续 到 服务 器 的 请 求 都 将 返回 该 Cookie， 明 确 地 将 请 


pene 会 话 跟 踪 cookie 的 标准 名 字 必 须 是 JSESSIONID。 容 器 也 人 允许 通过 容器 指定 
的 配置 自 定 义 会 话 跟踪 cookie 的 名 字 。 


所 有 servlet 容器 必须 提供 能 够 配置 容器 是 否 标 记 会 话 跟踪 cookie 为 HttpOnly 的 能 力 。 已 建立 
的 配置 必须 应 用 到 所 有 上 下 文中 还 没有 建立 特定 的 配置 ( 见 SessionCookieConfig javadoc 获 
取 更 多 细节 ) 。 


如 果 web 应 用 为 其 会 话 跟踪 cookie 配置 了 一 个 自 定 义 的 名 字 ， 则 如 果 会 话 id 编码 到 URL 中 
那么 相同 的 自 定义 名 字 也 将 用 于 URI 参数 的 名 字 (假如 URL 重 写 已 开启 ) > 
SSL 会 话 


安全 套 接 字 层 (Secure Sockets Layer) > Æ HTTPS 使 用 的 加 密 技 术 ， 有 一 种 内 置 机 制 允 许多 
个 来 自 客户 端的 请 求 被 明确 识别 为 同一 会 话 。Servlet 容 器 可 以 很 容易 地 使 用 该 数据 来 定义 会 
T& o 


URL £5 


URL 重 写 是 会 话 跟踪 的 最 低 标准 。 当 客户 端 不 接受 cookie 时 ， 服 务 器 可 使 用 URL 重 写作 为 
会 话 跟踪 的 基础 。URL 重 写 涉及 添加 数据 、 会 话 |D、 容 器 解析 URL 路 径 从 而 请 求 与 会 话 相 
关联 。 


会 话 ID 必须 被 编码 为 URL 字符 串 中 的 一 个 路 径 参 数 。 参 数 的 名 字 必 须 是 jsessionid。 下 面 是 
一 个 URL 包含 编码 的 路 径 信息 的 例子 


http://www.myserver.com/catalog/index.html;jsessionid=1234 

URL 重 写 在 日 志 、 书 签 、referer header、 缓 存 的 HTML、URL 工 具 条 中 暴露 会 话 标识 。 在 支 
持 cookie 或 SSL 会 话 的 情况 下 ， 不 应 该 使 用 URL 重 写 作为 会 话 跟 踪 机 制 。 

会 话 完整 性 


当 服务 的 来 自 客 户 端的 请 求 不 | cookie 时 ，Web 容器 必须 能 够 支持 HTTP 会 话 。 为 
了 满足 这 个 要 求 ，Web 容器 通常 支持 URL 重 写 机 制 。 


会 话 跟踪 机 制 
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创建 会 话 


当 会 话 仅 是 一 个 未 来 的 且 还 没有 被 建立 时 会 话 被 认为 是 “新 "的 。 因 为 HTTP 是 一 种 基于 请 求 - 响 
应 的 协议 ， 直 到 客户 端 " 加 入 "到 HTTP 会 话 之 前 它 都 被 认为 是 新 的 。 当 会 话 跟踪 信息 返回 到 服 
务 器 指示 会 话 已 经 建立 时 客户 端 加 入 到 会 话 。 直 到 客户 端 加 入 到 会 话 ， 不 能 假定 下 一 个 来 自 
客户 端的 请 求 被 识别 为 同一 会 话 。 


如 果 以 下 之 一 是 true， 会 话 被 认为 是 “新 "的 : 


© 客户 端 还 不 知道 会 
e 客户 端 选 择 is o 
这 些 条 件 定义 了 servlet 容器 没有 机 制 能 把 一 个 请 求 与 之 前 的 请 求 相 关联 的 情况 。 


servlet 开发 人 员 必 须 设 计 他 的 应 用 以 便 处 理 客户 端 没 有 ， 不 能 ， 或 不 会 加 入 会 话 的 情况 


与 每 个 会 话 相 关联 是 一 个 包含 唯一 标识 符 的 字符 串 ， 也 被 称 为 会 话 ID。 会 话 ID 的 值 能 通过 调 
用 javax.servlet.http.HttpSession.getId() 获取 ， 且 能 在 创建 后 通过 调 


用 javax.servlet.http.HttpServletRequest.changeSessioniId() 改变 。 
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HttpSession 对 象 必 须 被 限定 在 应 用 【或 servlet 上 下 文 ) 级 别 。 底 层 的 机 制 ， 如 使 用 cookie 
建立 会 话 ， 不 同 的 上 下 文 可 以 是 相同 ， 但 所 引用 的 对 象 ， 包 括 包括 该 对 象 中 的 属性 ， 决 不 能 
在 容器 上 下 文 之 间 共 享 。 


用 一 个 例子 来 说 明 该 要 求 : 如 果 servlet 使 用 RequestDispatcher 来 调用 另 一 个 Web 应 用 的 
servlet， 任 何 创建 的 会 话 和 被 调用 servlet 所 见 的 必须 不 同 于 来 自 调用 会 话 所 见 的 。 

此 外 ， 一 个 上 下 文 的 会 话 在 请 求 进入 那个 上 下 文 时 必须 是 可 恢复 的 ， 不 管 是 直接 访问 它们 关 
联 的 上 下 文 还 是 在 请 求 目 标 分 派 时 创建 的 会 话 。 


绑 定 属性 到 会 话 


servlet 可 以 按 名 称 绑 定 对 象 属性 到 HttpSession 实现 ， 任 何 绑 定 到 会 话 的 对 象 可 用 于 任意 其 
他 的 servlet， 其 属于 同一 个 ServletContext 且 处 理 属 于 相同 会 话 中 的 请 求 。 一 些 对 象 可 能 需 
要 在 它们 被 放 进 会 话 或 从 会 话 中 移 除 时 得 到 通知 。 这 些 信息 可 以 从 
HttpSessionBindingListener 接口 实现 的 对 象 中 获取 。 这 个 接口 定义 了 以 下 方法 ， 用 于 标识 一 
个 对 象 被 绑 定 到 会 话 或 从 会 话 解除 绑 定 时 。 

e valueBound 


e valueUnbound 


在 对 象 对 HttpSession 接口 的 getAttribute 方法 可 用 之 前 valueBound 方法 必须 被 调用 。 在 对 
象 对 HttpSession 接口 的 getAttribute 方法 不 可 用 之 后 valueUnbound 方法 必须 被 调用 。 


会 话 超时 


在 HTTP 协议 中 ， 当 客户 端 不 再 处 于 活动 状态 时 没有 显示 的 终止 信号 。 这 意味 着 当 客 户 端 不 
再 处 于 活跃 状态 时 可 以 使 用 的 唯一 机 制 是 超时 时 ie 


Servlet 容器 定义 了 默认 的 会 话 超时 时 间 ， 且 可 以 通过 HttpSession 接口 的 
getMaxlnactivelnterval 方法 获取 。 开 发 人 员 可 以 使 用 HttpSession 接口 的 
setMaxlnactivelnterval 方法 改变 超时 时 间 。 这 些 方 法 的 超时 时 间 以 秒 为 单位 。 根 据 定 义 ， 如 
果 超 时 时 间 设 置 为 0 或 更 小 的 值 ， 会 话 将 永 不 过 期 。 会 话 不 会 失效 ， 直 到 所 有 servlet 使 用 的 
会 话 已 经 退出 其 service 方法 。 一 旦 会 话 已 失效 ,新 的 请 求 必须 不 能 看 到 该 会 话 。 


最 后 访问 时 间 


HttpSession 接口 的 getLastAccessedTime 方法 允许 servlet 确定 在 当前 请 求 之 前 的 会 话 的 最 
后 访问 时 间 。 当 会 话 中 的 请 求 是 servlet 容器 第 一 个 处 理 时 该 会 话 被 认为 是 访问 了 。 


重要 会 话语 义 


多 线程 问题 


在 同一 时 间 多 个 servlet 执行 请 求 的 线程 可 能 都 有 到 同一 会 话 的 活跃 访问 。 容 器 必须 确保 ， 以 
一 种 线程 安全 的 方式 维护 表示 会 话 属 性 的 内 部 数据 结构 。 开 发 人 员 负 责 线 程 安全 的 访问 属性 
对 象 本 身 。 这 样 将 防止 并 发 访问 HttpSession 对 象 内 的 属性 集合 ， 消 除了 应 用 程序 导致 破坏 集 
合 的 机 会 。 


分 布 式 环境 


在 一 个 标识 为 分 布 式 的 应 用 程序 中 ， 会 话 中 的 所 有 请 求 在 同一 时 间 必 须 仅 被 一 个 JVM 处 理 。 
容器 必须 能 够 使 用 适当 的 setAttribute 或 putValue 方法 把 所 有 对 象 放 入 到 HttpSession 类 实 
例 。 以 下 限制 被 强加 来 满足 这 些 条 件 : 


。 容器 必须 接受 实现 了 Serializable 接口 的 对 象 。 

e. 容器 可 以 选择 支持 其 他 指定 对 象 存 储 在 HttpSession 中 ， 如 Enterprise JavaBeans 组 件 
、 o 

e. 由 特定 容器 的 设施 处 理会 话 迁 移 。 


当 分 布 式 servlet 容器 不 支持 必需 的 会 话 迁 移 存储 对 象 机 制 时 容器 必须 抛 出 
lllegalArgumentException ° 


分 布 式 servlet 容器 必须 支持 迁移 的 对 象 实现 Serializable 的 必要 机 制 。 


制 意味 着 开发 人 员 确保 除 在 非 分 布 式 容器 中 遇 到 的 问题 没有 额外 的 并 发 问题 。 


be 
上 


容器 供应 商 可 以 确保 可 扩展 性 和 服务 质量 的 功能 ， 如 负载 平衡 和 故障 转移 通过 把 会 话 对 象 和 
它 的 内 容 从 分 布 式 系统 的 任意 一 个 活跃 节点 移动 到 系统 的 一 个 不 同 的 节点 上 。 


果 分 布 式 容器 持久 化 或 迁移 会 话 提供 服务 质量 特性 ， 它 们 不 限制 使 用 原生 的 JVM 序列 化 机 
。 HttpSession 和 它们 的 属性 。 如 果 开 发 人 员 实 现 session 属性 上 的 readObject 
和 writeObject 方法 ， 他 们 也 不 能 保证 容器 将 调用 这 些 方法 ， 但 保证 Serializable 结束 它们 的 
属性 将 被 保存 。 


容器 必须 在 迁移 会 话 时 通知 实现 了 HttpSessionActivationListener 的 所 有 会 话 属性 。 它 们 必须 
在 序列 化 会 话 之 前 通知 印 化 监听 器 ， 在 反 序 列 化 之 后 通知 激活 监听 器 


写 分 布 式 应 用 的 开发 人 员 应 该 意识 到 容器 可 能 运行 在 多 个 Java 虚拟 机 中 ， 开 发 人 员 不 能 依赖 
静态 变量 存储 应 用 状态 。 他 们 应 该 用 企业 Bean 或 数据 库存 储 这 种 状态 。 


从 客户 端 应 用 程序 发 起 的 到 servlet 容器 的 请 求 可 能 在 同一 会 话 。 为 了 最 大 的 可 移植 性 ， 开 发 
人 员 应 该 假定 客户 端 所 有 窗口 参与 同一 会 话 。 


注解 和 可 插 拔 性 


本 章 描述 了 注解 的 使 用 和 使 web 应 用 内 使 用 的 框架 和 库 能 够 可 插 拔 的 增强 。 


注解 和 可 插 拔 性 


在 web 应 用 中 ， 使 用 注解 的 类 仅 当 它们 位 于 WEB-INF/classes 目录 中 ， 或 它们 被 打包 到 位 于 
应 用 的 WEB-INF/lib 中 的 jar 文件 中 时 它们 的 注解 才 将 被 处 理 。 


Web 应 用 部 署 描述 符 的 web-app 元 素 包含 一 个 新 的 “metadata-complete” 属 性 。“metadata- 
complete" 属 性 定义 了 web 描述 符 是 否 是 完整 的 ， 或 是 否 应 该 在 部 署 时 检查 jar 包 中 的 类 文件 
和 web fragments。 如 果 “metadata-complete” 设置 为 “true”， 部 署 工 具 必 须 必须 忽略 存在 于 
应 用 的 类 文件 中 的 所 有 指定 部 署 信息 的 servlet 注解 和 web fragments。 如 果 metadata- 
complete 属性 没有 指定 或 设置 为 "false”， 部 署 工具 必须 检查 应 用 的 类 文件 的 注解 ， 并 扫描 
web fragments ° 


以 下 注解 必须 被 Servlet 3.0 兼容 的 容器 支持 。 


@WebServlet 


该 注解 用 于 在 Web 应 用 中 定义 Servlet 组 件 。 该 注解 在 一 个 类 上 指定 并 包含 声明 Servlet 的 元 
数据 。 必 须 指 定 注解 的 urlPatterns 或 value 属 性 。 所 有 其 他 属性 是 可 选 的 默认 设置 (请 参考 
javadoc 获取 更 多 细节 ) 。 当 注解 上 唯一 属性 是 url 模式 时 推荐 使 用 value 且 当 也 有 使 用 其 他 
属性 时 使 用 urlPatterns 属性 。 在 同一 注解 上 同时 使 用 value 和 urlPatterns 属性 是 非法 的 。 如 
果 没 有 指定 Servlet 名 字 则 默认 是 全 限定 类 名 。 被 注解 的 sevlet 必须 指定 至 少 一 个 url 模式 进 
行 部 署 。 如 果 同 一 个 Servlet 类 以 不 同 的 名 字 上 声明 在 部 署 描述 符 中 ， 必 须 实例 化 一 个 新 的 
Servlet 实例 。 如 果 使 用 不 同名 字 添 加 的 同一 个 Servlet 类 使 用 定义 在 4.4.1 节 “编程 式 添加 和 配 
i. Servlet 的 编程 式 API 添加 到 ServletContext， 使 用 @WebServlet 注解 声明 的 属性 值 必 须 
被 忽略 ， 必 须 创 建 一 个 指定 名 字 的 Servlet 的 新 的 实例 。 @WebServlet 注解 的 类 必须 继承 
javax.servlet.http.HttpServlet%& ° 


下 面 是 如 何 使 用 该 注解 的 一 个 示例 。 
CODE EXAMPLE 8-1 @WebServlet Annotation Example 
QWebServlet("/foo") 


public class CalculatorServlet extends HttpServlet( 
OA 


} 
下 面 是 如 何 使 用 该 注解 指定 更 多 的 属性 的 一 个 示例 。 


CODE EXAMPLE 8-2 @WebServlet annotation example using other annotation attributes 
specified 


QWebServlet(name="MyServlet", urlPatterns={"/foo", "/bar"}) 

public class SampleUsingAnnotationAttributes extends HttpServlet{ 
public void doGet(HttpServletRequest req, HttpServletResponse res) { 
} 


@WebFilter 


该 注解 用 于 在 Web 应 用 中 定义 Filter。 该 注解 在 一 个 类 上 指定 且 包 含 声 明 过 滤器 的 元 数据 。 
如 果 没 有 指定 Filter 名 字 则 默认 是 全 限定 类 名 。 注 解 的 urlPatterns 属性 , servletNames 属性 
或 value 属性 必须 被 指定 。 所 有 其 他 属性 是 可 选 的 默认 设置 (请 参考 javadoc 获取 更 多 细 
节 ) 。 当 注解 上 唯一 属性 是 url 模式 时 推荐 使 用 value 且 当 也 有 使 用 其 他 属性 时 使 用 
urlPatterns 属性 。 在 同一 注解 上 同时 使 用 value 和 urlPatterns 属性 是 非法 的 。 


@WebFilter 注解 的 类 必须 实现 javax.servlet.Filter。 

下 面 是 如 何 使 用 该 注解 的 一 个 示例 。 

CODE EXAMPLE 8-3 @WebFilter annotation example 
@webFilter(“/foo” ) 


public class MyFilter implements Filter { 
public void doFilter(HttpServletRequest req, HttpServletResponse res) 


{ 
} 
} 
@WeblinitParam 


该 注解 指定 了 必须 要 传递 给 Servlet 或 Filter 的 初始 化 参数 。 这 个 是 WebServlet 和 WebFilter 
注解 的 属性 之 一 。 


@WebListener 


WebListener 注解 用 于 注解 用 来 获得 特定 web 应 用 上 下 文中 的 各 种 操作 事件 的 监听 器 。 
@WebListener 注解 的 类 必须 实现 以 下 接口 : 


e javax.servlet.ServletContextListener 

e javax.servlet.ServletContextAttributeListener 
e javax.serviet.ServietRequestListener 

e javax.serviet.ServietRequestAttributeListener 
e javax.serviet.http.HttpSessionListener 

e javax.servlet.http.HttpSessionAttributeListener 


e javax.serviet.http.HttpSessionldListener 


一 个 例子 : 


@webListener 
public class MyListener implements ServletContextListener { 
public void contextInitialized(ServletContextEvent sce) { 
ServletContext sc = sce.getServletContext(); 
sc.addServlet("myServlet", "Sample servlet", "foo.bar.MyServlet", null, -1); 
sc.addServletMapping("myServlet", new String[] {"/urlpattern/*" }); 


@MultipartConfig 


该 注解 ， 当 指定 在 Serviet LN > ATH RAZ Æ mime/multipart 类 型 。 相 应 servlet 的 
HttpServletRequest 对 象 必 须 使 用 getParts 和 getPart 方法 遍历 各 个 mime 附件 以 获取 mime 
附件 。javax.servlet.annotation.MultipartConfig 的 location 属性 和 <multipart- 

config> 的 <location> 元 素 被 解析 为 一 个 绝对 路 径 且 默认 为 javax.servlet.context.tempdir ° 4 
果 指 定 了 相对 地 址 ， 它 将 是 相对 于 tempdir 位 置 。 绝 对 路 径 与 相对 地 址 的 测试 必须 使 用 
java.io.File.isAbsolute ° 


其 他 注解 /惯例 


除了 这 些 注解 ， 定 义 在 第 15.5 节 的 “注解 和 资源 注入 "将 继续 工作 在 这 些 新 注解 上 下 文中 。 


默认 情况 下 ， 所 有 应 用 将 有 index.htm(l) 和 index.jsp 在 welcome-file-list 列表 中 。 该 描述 符 可 
以 用 来 覆盖 这 些 默 认 设 置 。 当 使 用 注解 时 ， 从 WEB-INF/classes 或 WEB-INF/lib 中 的 不 同 框 
RK jar 包 / 类 加 载 监听 器 、Servlet 的 顺序 是 没有 指定 的 。 如 果 顺 序 是 很 重要 的 ， 那 么 请 看 


web.xml 模块 部 分 和 后 面 的 web.xml 和 web-fragment.xml 顺序 部 分 。 顺 序 仅 能 在 部 署 描述 符 
中 指定 。 


可 播 拔 性 


web.xml iz 3% 


使 用 上 述 定义 的 注解 ， 使 得 web.xml 4918 FEA To A > MTR RUA RAŽ JA eR AE 
置 的 值 ， 仍 然 需 要 使 用 部 署 描 述 符 。 如 前 所 述 ， 如 果 web.xml 描述 符 中 的 metadata- 
complete 元 素 设 置 为 true， 则 存在 于 class 文件 和 绑 定 在 jar 包 中 的 web-fragments 中 的 指 
定 部 署 信息 的 注解 将 不 被 处 理 。 这 意味 着 ， 所 有 应 用 的 元 数据 通过 web.xml 描述 符 指定 。 


为 了 给 开发 人 员 更 好 的 可 播 拔 性 和 更 少 的 配置 ， 在 这 个 版 本 的 规范 中 ， 我 们 引入 了 web 模块 
部 署 描 述 符 片段 (web fragment) 的 概念 。web fragment 是 web.xml 的 部 分 或 全 部 ， 可 以 在 
一 个 类 库 或 框架 jar 包 的 META-INF 目录 指定 和 包括 。 在 WEB-INF/lib 目录 中 的 普通 的 老 的 
jar 文件 即使 没有 web-fragment.xml 也 可 能 被 认为 是 一 个 fragment， 任 何在 它 中 指定 的 注解 
都 将 按照 定义 在 8.2.3 节 的 规则 处 理 ， 容 器 将 会 取出 并 按照 如 下 定义 的 规则 进行 配置 。 


web fragment 是 web 应 用 的 一 个 逻辑 分 区 ， 以 这 样 一 种 方式 ， 在 应 用 中 使 用 的 框架 可 以 定义 
所 有 制品 (artifact) 而 无 需要 求 开发 人 员 在 web.xml 中 编辑 或 添加 信息 。 它 几乎 包含 web.xml 
描述 符 中 使 用 的 所 有 相同 元 素 。 不 过 描述 符 的 顶级 元 素 必须 是 web-fragment 且 对 应 的 描述 符 
文件 必须 被 称 为 web-fragment.xml， 相 关 元 素 的 顺序 在 web-fragment.xml 和 web.xml 也 是 不 
同 的 ， 请 参考 定义 在 第 14 章 的 部 署 描 述 符 一 章 中 对 应 的 web-fragment schema ° 


如 果 框 架 打包 成 jar 文件 ， 且 有 部 署 描述 符 的 形式 的 元 数据 信息 ， 那 么 web-fragment.xml 描述 
符 必须 在 该 jar 包 的 META-INF/ 目录 中 。 如果 框 架 想 使 用 META-INF/web-fragment.xml， 以 
这 样 一 种 方式 ， 它 扩充 了 web 应 用 的 web.xml， 框 架 必 须 被 绑 定 到 Web 应 用 的 WEB-INF/lib 
目录 中 。 为 了 使 框架 中 的 任何 其 他 类 型 的 资源 〈 例 如 ， 类 文件 ) 对 web 应 用 可 用 ， 把 框架 放 
置 在 web 应 用 的 classloader 委托 链 的 任意 位 置 即 可 。 换 名 话说 ， 只 有 绑 定 到 web 应 用 的 
WEB-INF/lib 目录 中 的 JAR 文件 ， 但 不 是 那些 在 类 装载 委托 链 中 更 高 的 ， 需 要 扫描 其 web- 
fragment.xml ° 


在 部 署 期 间 ， 容 器 负责 扫描 上 面 指定 的 位 置 和 发 现 web-fragment.xml 并 处 理 它们 。 存 在 于 当 
前 的 单个 web.xml 的 名 字 唯 一 性 的 要 求 ， 也 同样 适用 于 一 组 web.xml 和 所 有 能 适用 的 web- 
fragment.xml 文件 。 


如 下 是 库 或 框架 可 以 包括 什么 的 例子 。 


<web-fragment> 
<servlet> 
<servlet -name>welcome</servlet -name> 
<servlet-class> 
WelcomeServlet 
</servlet-class> 
</servlet> 
<listener> 
<listener-class> 
RequestListener 
</listener-class> 
</listener> 
</web-fragment> 


以 上 的 web-fragment.xml 将 被 包括 在 框架 的 jar 文件 的 META-INF/ 目录 。web-fragment.xml 
配置 和 应 该 应 用 的 注解 的 顺序 是 未 定义 的 。 如 果 顺 序 对 于 某 一 应 用 是 很 重要 的 方面 ， 请 参考 
下 面 如 何 实现 所 需 的 顺序 定义 的 规则 。 


web.xml 和 web-fragment.xml 顺序 


由 于 规范 允许 应 用 配置 由 多 个 配置 文件 组 成 (web.xml 和 web-fragment.xml) 的 资源 ， 从 应 
用 中 多 个 不 同位 置 发 现 和 加 载 ， 顺 序 问题 必须 被 解决 。 本 节 详 述 了 配置 资源 的 作者 如 何 声 明 
他 们 制品 (artifact) 的 顺序 要 求 。web-fragment.xml 可 以 有 一 个 javaee:java-identifierType 类 
型 的 顶级 元 素 ， 且 在 一 个 web-fragment.xml 中 仅 能 有 一 个 元 素 。 如 果 存 在 一 个 元 素 ， 它 必须 
考虑 用 于 artifact 顺 序 〈 除 非 出 现 重 复 名 异常 ， 如 上 文 所 述 ) 。 两 种 情况 必须 被 考虑 ， 以 允许 
应 用 程序 配置 资源 来 表达 它们 的 顺序 配置 。 


1. 绝对 顺序 : 在 web.xml 中 的 <absolute-ordering> 元 素 。 在 一 个 web.xml 中 仅 能 有 一 
个 <absolute- ordering> 元 素 2 

o 在 这 种 情况 下 ， 第 二 种 情况 处 理 的 顺序 配置 必须 被 忽略 。 

o web.xml 和 WEB-INF/classes 必须 在 列 在 absolute-ordering 元 素 中 的 所 有 web- 
fragment 之 前 处 理 。 

o <absolute-ordering> 的 任何 直接 子 <name> 元 素 必须 被 解释 为 在 这 些 被 指定 的 web- 
fragment 中 表示 绝对 顺序 ， 不 管 它 存 不 存在 ， 必 须 被 处 理 。 

o <absolute-ordering> TAE 包含 零 个 或 一 个 <others /> 元 素 。 下 面 描述 此 元 素 必 需 的 
功能 。 如 果 <absolute-ordering> 元 素 没 有 包含 @ <others /> 元 素 没有 在 <name 
/> 明确 提 到 的 web-fragment 必须 被 忽略 。 不 会 扫描 被 排除 的 jar 包 中 的 注解 
Servlet ` Filter 或 Listener。 然 而 ， 如 果 是 被 排除 的 jar 包 中 的 servlet ` filter 或 
listener， 其 列 在 web.xml 或 非 排除 的 web-fragment.xml 中 ， 那 么 它 的 注解 将 使 用 除 
非 另 外 使 用 metadata-complete 排除 。 在 排除 的 jar 包 的 TLD 文件 中 发 现 的 
ServletContextListener 不 能 使 用 编程 式 API 配置 Filter 和 Servlet， 任 何 试图 这 样 做 
将 导致 llegalStateException。 如 果 发 现 的 ServletContainerlnitializer 是 从 一 个 被 排 
除 的 jar 包 中 装载 的 ， 它 将 被 忽略 。 无 论 是 否 设置 了 metadata-complete， 通 


过 <absolute-ordering> 排除 的 jar 包 不 扫描 被 任何 ServletContainerlnitializer 2b 22 44) 
类 o 

o 重复 名 字 异 常 : 如 果 ， 当 遍历 <absolute-ordering> 子 元 素 ， 遇 到 多 个 子 元 素 具 有 相 
E] <name> 元 素 ， 只 需 考 虑 首次 出 现 的 。 

2. 相对 顺序 : 在 web-fragment.xml 中 的 <ordering> 元 素 ， 一 个 web-fragment.xml 只 能 有 
一 个 <ordering> 元 素 。 

o web-fragment.xml 可 以 有 一 个 <ordering> 元 素 。 如 果 是 这 样 ， 该 元 素 必 须 包 含 零 个 

或 一 个 <before> 元 素 和 零 个 或 一 个 <after> 元 素 。 这 些 元 素 的 含义 在 下 面 进行 说 


明 o 
o web.xml 和 WEB-INF/classes 必须 在 列 在 ordering 元 素 中 的 所 有 web-fragment 之 
前 处 理 。 


o 重复 命名 异常 : 如 果 ， 当 遍历 web-fragments， 遇 到 多 个 成 员 具 有 相同 <name> 元 
ee A nacht 
失败 。 例 如 ， 一 种 解决 该 问题 的 办 法 是 用 户 使 用 绝对 顺序 ， 在 这 种 情况 下 相对 顺序 
被 忽略 。 

o 思考 这 个 简短 的 但 具 说 明 下 的 例子 。3 个 web-fragment - MyFragment1 ` 
MyFragment2 和 MyFragment3 作为 应 用 一 部 分 ， 同 时 也 包括 一 个 web.xml。 


web-fragment.xml 


<web-fragment> 
<name>MyFragment1</name> 
<ordering><after><name>MyFragment2</name></after></ordering> 


</web-fragment> 


web-fragment.xml 


<web -fragment> 
<name>MyFragment2</name> 


</web-fragment> 


web-fragment.xml 


<web -fragment> 
<name>MyFragment3</name> 
<order ing><before><others/></before></ordering> 


</web-fragment> 


web.xml 


<web - app> 


</web -app> 


在 该 示例 中 ， 处 理 顺 序 将 是 : 

web.xml 

MyFragment3 

MyFragment2 

MyFragment1 

前 面 的 示例 说 明了 一 些 ,但 不 是 全 部 ,以 下 是 全 部 原则 。 


e <before> 意味 着 文档 必须 被 安排 在 指定 在 诅 套 <name> 元 素 的 name 匹配 的 文档 之 前 。 
© <after> 意味 着 文档 必须 被 安排 在 指定 在 襄 套 <name> 元 素 的 name 匹 配 的 文档 之 后 。 
e 在 <before> 或 <after> 可 以 包括 特殊 的 <others/> 元 素 零 次 或 一 次 ， 或 直接 包括 
在 <absolute-ordering> 元 素 中 零 次 或 一 次 。 <others/> 元 素 必 须 作 如 下 处 理 。 
o 如 果 <before> 元 素 包含 一 个 瞬 套 的 <others/> ， 该 文档 将 被 移动 到 有 序 的 文档 列表 
开头 。 如 果 有 多 个 文档 指定 <before><others/> ， 则 它们 将 都 在 有 序 的 文档 列表 开 
头 ， 但 该 组 文档 的 顺序 是 未 指定 的 。 
o 如 果 <after> 元 素 包含 一 个 瞪 套 的 <others/> ， 该 文档 将 被 移动 有 序 的 文档 列表 末 
尾 。 如 果 有 多 个 文档 指定 <after><others/> ， 则 它们 将 都 在 有 序 的 文档 列表 末尾 ， 
但 该 组 文档 的 顺序 是 未 指定 的 。* 在 一 个 的 <before> 或 <after> 元 素 内 ， 如 果 存 在 
一 个 <others/> 元 素 ， 但 在 它 的 父 元 素 内 <name> 元 素 不 是 唯一 的 ， 父 元 素 内 的 其 他 
元 素 必 须 按 照 顺 序 处 理 。 
o 如 果 <others/> 直接 出 现在 <absolute-ordering> 内 ， runtime 必须 确保 任何 web- 
fragment 未 明确 指定 在 <absolute-ordering> 部 分 的 以 处 理 的 顺序 包括 在 这 一 点 上 。 
* 如 果 web-fragment.xml 文件 没有 <ordering> 或 web.xml 没有 <absolute-ordering> 元 
素 ， 则 artifact 被 假定 没有 任何 顺序 依赖 。 
e 如 果 runtime 发 现 循 环 引 用 ， 必 须 记录 提供 有 用 信息 的 消息 ， 应 用 必须 部 署 失 败 。 此 外 ， 
用 户 采 取 的 一 系列 动作 可 能 是 在 web.xml 中 使 用 绝对 顺序 。 
。 之 前 的 示例 可 以 被 扩展 以 说 明 当 web.xml 包含 顺序 部 分 的 情况 


web.xml 


<web -app> 
<absolute-ordering> 
<name>MyFragment3</name> 
<name>MyFragment2</name> 
</absolute-ordering> 


</web -app> 


在 该 示例 中 ， 各 种 元 素 的 顺序 将 是 : 

web.xml 

MyFragment3 

MyFragment2 

下 面包 括 了 一 些 额外 的 示例 场景 。 所 有 这 些 适用 于 相对 顺序 且 不 是 绝对 顺序 。 


Document A : 


<after> 
<others/> 
<name> 
C 
</name> 
</after> 


Document B: 


<before> 
<others/> 
</before> 


Document C: 


<after> 
<others/> 
</after> 


Document D : 没有 指定 顺序 
Document E : 没有 指定 顺序 


Document F : 


<before> 
<others/> 
<name> 
B 
</name> 
</before> 


产生 的 解析 顺序 : 
web.xml, F, B, D, E, C, A。 


Document : 


<after> 
<others/> 
</after> 
<before> 
<name> 
C 
</name> 
</before> 


Document B: 


<before> 
<others/> 
</before> 


Document C: 没有 指定 顺序 


Document D: 


<after> 
<others/> 
</after> 


Document E: 


<before> 
<others/> 
</before> 


Document F : 没有 指定 顺序 


产生 的 解析 顺序 可 能 是 下 列 之 一 : 


e B,E,F,,C,D 


e B,E,F,,D,C 
e E,B,F,,C,D 
e E,B,F,,D,C 
e E,B,F,D,,C 
e B,E,F,D,,C 
Document A : 
<after> 
<name> 
B 
</name> 
</after> 


Document B : 没有 指定 顺序 


Document C : 


<before> 
<others/> 
</before> 


Document D: 没有 指定 顺序 


产生 的 解析 顺序 : C, B,D, A。 解 析 的 顺序 也 可 能 是 : C, D,B,A 或 C,B,A,D 


装配 web.xml ` web-fragment.xml 描述 符 和 注解 


如 果 对 于 一 个 应 用 Listener ` Servlet 和 Filter 的 调用 顺序 是 很 重要 的 ， 那 么 必须 使 用 部 署 描 
述 符 。 同 样 ， 如 果 有 必要 ， 可 以 使 用 上 面 定义 的 顺序 元 素 。 如 上 所 述 ， 当 使 用 注解 定义 
Listener ` Servlet 和 Filter， 它 们 调用 的 顺序 是 未 指定 的 。 下 面 是 用 于 装配 应 用 程序 的 最 终 部 
署 描述 符 的 一 组 规则 : 


1. w RA XHY Listener ` Servlet 和 Filter 的 顺序 必须 指定 ， 那 么 必须 在 web-fragment.xml 
或 web.xml 中 指定 。 
2. 顺序 将 依据 它们 定义 在 描述 符 中 的 顺序 ， 和 依赖 于 web.xml 中 的 absolute-ordering 元 素 
或 web-fragment.xml 中 的 ordering 元 素 ， 如 果 存 在 的 话 。 
o 匹配 请 求 的 过 滤器 链 的 顺序 是 它们 在 web.xml 中 声明 的 顺序 。 
o Servlet 在 请 求 处 理 时 实例 化 或 在 部 署 时 立即 实例 化 。 在 后 一 种 情况 ， 以 它们 的 load- 
on-startup 元 素 指 定 的 顺序 实例 化 。 
o 在 之 前 发 布 的 规范 ， 上 下 文 Listener 以 随机 顺序 调用 。 在 Servlet3.0，Listener 以 它们 
在 web.xml 中 声明 的 顺序 调用 ， 如 下 所 示 : 


javax.servlet.ServletContextListener 实 现 的 contextlnitialized 方 法 以 声明 时 顺序 
调用 ，contextDestroyed 以 相反 顺序 调用 。 
javax.servlet.ServletRequestListener 实现 的 requestlinitialized 以 声明 时 顺序 调 
用 ，requestDestroyed 方法 以 相反 顺序 调用 。 
javax.servlet.http.HttpSessionListener 实现 的 sessionCreated 方 法 以 声明 时 顺序 
调用 ，sessionDestroyed 方法 以 相反 顺序 调用 。 

当 相 应 的 事件 触发 时 ，javax.servlet.ServletContextAttributeListener、 
javax.servlet.ServletRequestAttributeListener 和 
javax.servlet.HttpSessionAttributeListener 的 方法 按照 它们 声明 的 顺序 调用 。 


o 如 果 在 web.xml 使 用 enabled 元 素 禁 用 引入 的 servlet， 那 么 该 servlet 对 指定 的 url- 
pattern 不 可 用 。 

o 当 在 web.xml、web-fragment.xml 和 注解 之 间 解 析 发 生 冲 突 时 web 应 用 的 web.xml 
具有 最 高 优先 级 。 

o 如 果 没 有 在 描述 符 中 指定 metadata-complete 或 在 部 署 描述 符 中 设置 为 false， 通 过 
组 合 出 现在 注解 和 描述 符 中 的 metadata 寻 出 有 效 的 metadata。 合 并 的 规则 具体 如 


Ti 


在 web fragment 中 的 配置 设置 用 于 扩充 那些 已 指定 在 主 Web.xml 的 配置 设置 ， 使 
用 这 种 方式 就 好 像 它 们 指定 在 同一 个 web.xml。 
添加 到 主 web.xml 的 web fragment 中 的 配置 设置 的 顺序 由 8.2.2 节 “web.xml 和 
web-fragment.xml 顺 序 ” 指 定 。 
当主 web.xml 的 metadata-complete 属性 设置 为 true， 被 认为 是 完整 的 且 在 部 署 
时 不 会 扫描 注解 和 fragment。 如 果 有 absolute-ordering 和 ordering 元 素 将 被 忽 
略 。 当 设置 fagment 上 的 为 true 时 ，metadata-complete 属 性 仅 适 用 于 在 特定 的 
jar 包 中 扫描 注解 。 
除非 metadata-complete 设置 为 true， 和 否则 web fragmentit + # 2] web.xml 。 
合并 发 生 在 相关 fragment 的 注解 处 理 之 后 。 
当 使 用 web fragment 扩 充 web.xml 时 以 下 被 认为 配置 冲突 : 
m 多 个 元 素 使 用 相同 的 但 不 同 的 
m 多 个 元 素 使 用 相同 的 但 不 同 的 
上 面 的 配置 冲突 被 解析 为 如 下 : 
= 在 主 web.xml 和 web fragment 之 问 的 配置 冲突 被 解析 为 在 web.xml 的 配置 具 
有 高 优先 级 。 
= 在 两 个 web fragment 之 间 的 配置 冲突 ， 冲 突 的 中 心 元 素 没 有 出 现在 主 
Web.xml， 将 导致 一 个 错误 。 必 须 记录 一 个 有 用 的 消息 ， 且 应 用 必须 部 署 失 
败 。 
上 面 的 冲突 被 解析 后 ， 这 些 额外 的 规则 适用 : 
a 可 以 在 多 个 web-frament 中 声明 任意 多 次 元 素 并 生成 到 web.xml。 比 如 ， 元 
素 可 以 以 不 同 的 名 字 添 加 。 
u 如 果 指 定 在 web.xml 中 的 履 盖 了 指定 在 web-fragment 中 的 同名 的 值 ， 则 可 以 
声明 任意 多 次 元 素 。 


u 如 果 是 最 少 出 现 零 次 且 最 多 出 现 一 次 的 元 素 存 在 于 web fragment? LAA 
在 主 web.xml 中 ， 则 主 web.xml 继 承 web fragment 的 设置 。 如 果 元 素 出 现在 
主 web.xml 和 web fragment， 则 主 web.xml 的 配置 设置 具有 高 优先 级 。 例 
如 ， 如 果 在 主 web.xml 和 web fragment 中 都 声明 了 相同 的 servlet， 且 声明 在 
web fragment 中 的 servlet 指 定 了 元 素 ， 且 没 在 主 web.xml 指 定 ， 则 web 
fragment 的 元 素 将 被 使 用 并 合并 到 web.xml。 

u 如 果 是 最 少 出 现 零 次 且 最 多 出 现 一 次 的 元 素 指定 在 两 个 web fragment » A 
没有 出 现在 主 web.xml， 则 认为 是 错误 的 。 例 如 ， 如 果 两 个 web fragment # 
明了 相同 的 Servlet， 但 具有 不 同 的 元 素 ， 且 相同 的 Servlet 也 声明 在 主 
Web.xml， 但 没有 ， 则 必须 报告 一 个 错误 。 

m 声明 是 可 添加 的 。 

m 具有 相同 的 元 素 可 以 添加 到 多 个 web-fragment。 在 web.xml 中 指定 的 覆盖 在 
web-fragment 中 指定 的 同名 的 的 。 

具有 相同 的 元 素 可 以 添加 到 多 个 web-fragment。 在 web.xml 中 指定 的 覆盖 在 
web-fragment 中 指定 的 同名 的 的 。 

m 具有 相同 的 多 个 元 素 被 当 作 一 个 声明 。 

合并 产生 的 web.xml 被 认为 是 ， 仅 当 所 有 它 的 web fragment 也 被 标记 为 。 

= web fragment 的 顶级 和 它 的 孩子 元 素 ，， 和 元 素 被 忽略 。 

= jsp-property-group 是 可 添加 的 。 当 绑 定 静态 资源 到 jar 包 的 META- 
INF/resources 目 录 ， 推 荐 jsp-config 元 素 使 用 url-pattern， 反 对 使 用 
extension 上 映射。 此外， 如 果 存 在 一 个 fragment 的 JSP 资 源 ， 则 应 该 在 一 个 
与 fagment 同 名 的 子 目 录 中 。 这 有 助 于 防止 一 个 web-fragment 的 jsp- 
property-group 受 到 来 自 应 用 的 主 docroot 中 的 JSP 的 影响 和 受到 来 自 一 个 
fragment 的 META-INF/resources 的 JSP 的 影响 。 

m 对 于 所 有 资源 引用 元 素 (env-entry, ejb-ref, ejb-local-ref, service-ref, resource- 
ref, resource-env-ref, message-destination-ref, persistence-context-ref and 
persistence-unit-ref) 如 下 规则 适用 : 

m 如 果 任 意 资 源 引 用 元 素 出 现在 web fragment， 主 web.xml 继 承 web fragment 
的 值 。 如 果 该 元 素 同时 出 现在 主 web.xml 和 web fragment， 使 用 相同 的 名 
字 ，web.xml 具 有 高 优先 级 。 所 有 fragment 的 子 元 素 除 下 面 指定 的 injection- 
target 被 合并 到 主 Web.xml。 例 如 ， 如 果 主 web.xml 和 web fragment 都 使 用 
相同 的 声明 一 个 ， 将 使 用 web.xml 中 的 且 不 会 合并 fragment 中 的 任意 子 元 素 
除 下 面 声 明 的 。 

a 如 果 资 源 引用 元 素 指定 在 两 个 fagment， 当 没有 指定 在 主 web.xml 中 ， 且 资 
源 引 用 元 素 的 所 有 属性 和 子 元 素 都 是 一 样 的 ， 资 源 引 用 将 被 合并 到 主 
web.xml。 如 果 使 用 相同 名 字 在 两 个 fragment 中 指定 资源 引用 元 素 ， 且 没有 
在 web.xml 中 指定 ， 属 性 和 子 元 素 是 不 一 样 的 ， 那 么 被 认为 是 错误 的 。 错 误 
必须 被 报告 且 应 用 必须 部 署 失败 。 例 如 ， 如 果 两 个 web fragment 使 用 相同 
的 声明 了 但 类 型 一 个 指定 为 javax.sdql.DataSource 另 一 个 指定 为 JavaMail， 
这 是 错误 的 且 应 用 必须 部 署 失败 。 


a 对 于 在 fragment 中 使 用 相同 名 称 的 的 资源 引用 元 素 将 被 合并 到 主 web.xml。 
a 除了 上 面 定义 的 web-fragment.xml 的 合并 规则 之 外 ， 下 面 的 规则 适用 于 使 
用 资源 引用 注解 (@Resource, @Resources, @EJB, @EJBs, 
@WebServiceRef, @WebServiceRefs, @PersistenceContext, 
@PersistenceContexts,@PersistenceUnit, and @PersistenceUnits) ° 如 果 
资源 引用 注解 应 用 到 类 上 ， 这 等 价 于 定义 了 一 个 资源 ， 但 是 这 不 等 价 于 定 
义 一 个 injection-target。 在 这 种 情况 下 上 述 规则 适用 于 injection-target 元 
素 。 如 果 在 字段 上 使 用 资源 引用 注解 ， 这 等 价 于 在 web.xml 定 义 injection- 
target 元 素 。 但 是 如 果 在 描述 符 中 没有 injection-target 元 素 ， 那 么 fagment 
中 的 injection-target 仍 将 被 合并 到 上 面 定 义 的 web.xml。 如 果 从 另 一 方面 来 
说 ， 在 主 web.xml 中 有 一 个 injection-target 并 同时 有 一 个 同 资源 名 的 资源 引 
用 注解 ， 那 么 这 被 认为 是 对 资源 引用 注解 的 覆盖 。 在 这 种 情况 下 ， 由 于 在 
描述 符 中 指定 了 一 个 injection-target， 上 述 定义 的 规则 将 适用 于 除了 和 履 盖 的 
资源 引用 注解 。 
= 如 果 在 两 个 fragment 中 指定 了 data-source 元 素 ， 而 没有 出 现在 主 web.xml， 且 
data-source 元 素 的 所 有 属性 和 子 元 素 都 是 一 样 的 ，data-source 将 被 合并 到 主 
web.xml。 如 果 在 两 个 fragment 中 指定 同名 的 data-source 元 素 ， 而 没有 出 现在 主 
Web.xml 且 两 个 fragment 的 属性 和 子 元 素 不 是 一 样 的 ， 这 被 认为 是 错误 的 。 在 这 
种 情况 下 ， 必 须 报 告 一 个 错误 且 引 用 必须 部 署 失败 。 


下 面 是 一 些 示 例 ， 展 示 了 在 不 同情 况 下 的 结果 。 
CODE EXAMPLE 8-4 

web.xml - 没有 resource-ref 的 定义 

Fragment 1 


web-fragment.xml 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target -name> 
baz 
</injection-target -name> 
</injection-target> 
</resource-ref> 


有 效 的 metadata 将 是 : 


<resource-ref> 


<resource-ref -name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target-name> 
baz 
</injection-target-name> 
</injection-target> 
</resource-ref> 


CODE EXAMPLE 8-5 


web.xml 


<resource-ref> 


<resource-ref-name="foo"> 


</resource-ref> 


Fragment 1 


web-fragment.xml 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target-name> 
baz 
</injection-target-name> 
</injection-target> 
</resource-ref> 


Fragment 2 


web-fragment.xml 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar2.class 
</injection-target-class> 
<injection-target-name> 
baz2 
</injection-target-name> 
</injection-target> 
</resource-ref> 


有 效 的 metadata 是 : 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target-name> 
baz 
</injection-target-name> 
</injection-target> 
<injection-target> 
<injection-target-class> 
com.foo.Bar2.class 
</injection-target-class> 
<injection-target-name> 
baz2 
</injection-target-name> 
</injection-target> 
</resource-ref> 


CODE EXAMPLE 8-6 


web.xml 


<resource-ref> 

<resource-ref -name="foo"> 

<injection-target> 
<injection-target-class> 

com.foo.Bar3.class 
</injection-target-class> 
<injection-target-name> 
baza 

</injection-target-name> 


</resource-ref> 


Fragment 1 


web-fragment.xml 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target-name> 
baz 
</injection-target-name> 
</injection-target> 
</resource-ref> 


Fragment 2 


web-fragment.xml 


<resource-ref> 


<resource-ref-name="foo"> 


<injection-target> 
<injection-target-class> 
com.foo.Bar2.class 
</injection-target-class> 
<injection-target-name> 
baz2 
</injection-target-name> 
</injection-target> 
</resource-ref> 


有 效 的 metadata 是 : 


<resource-ref> 
<resource-ref-name="foo"> 
<injection-target> 
<injection-target-class> 
com.foo.Bar3.class 
</injection-target-class> 
<injection-target-name> 
baz3 
</injection-target-name> 
<injection-target-class> 
com.foo.Bar.class 
</injection-target-class> 
<injection-target-name> 
baz 
</injection-target-name> 
<injection-target-class> 
com.foo.Bar2.class 
</injection-target-class> 
<injection-target-name> 
baz2 
</injection-target-name> 
</injection-target> 


</resource-ref> 


Fragment 1 和 2 的 <injection-target> 将 被 合并 到 主 web.xml 


* 如 果 主 web .Xml 没有 指定 任何 “<post-construct> 元素， 且 web-fragment 中 也 指定 了 <post-construct> 

， 那么 fragment 中 的 “<post-construct> 将 被 合并 到 主 web ,Xm1。 不 过 如 果 在 主 web ,xm1 中 至 少 指定 一 个 
“<post-construct> ` 元 素 ， 那 么 fragment 中 的 `“<post-construct> ` 将 不 被 合并 。 由 web .xml 的 作者 负责 确保 
`<post-construct> 列表 是 完成 的 。 
* 如 果 主 web .Xml 没有 指定 任何 `“<pre-destroy> A% > Aweb-fragment F44 £ T `<pre-destroy>` > M2 
fragment 中 的 `“<pre-destroy> ` 元 素 将 被 合并 到 主 web .xml。 不 过 如 果 在 主 web .xm1 中 至 少 指定 一 个 `“<pre-des 
troy> 元素， 那么 fragment 中 的 `“<pre-destroy> 将 不 被 合并 。 由 web .xml 的 作者 负责 确保 “<pre-destroy> 
列表 是 完成 的 。 
* 在 处 理 完 web-fragment .xml 之 后 ， 在 处 理 下 一 个 fragment 之 前 相应 fragment 的 注解 被 处 理 以 完成 有 效 的 meta 
data。 以 下 规则 用 于 处 理 注解 : 
* 通过 注解 指定 的 metadata， 尚 未 存在 于 描述 符 中 ， 将 被 用 来 扩充 有 效 的 描述 符 。 

* 指定 在 主 web .xm1 或 web fragment 中 的 配置 比 通过 注解 指定 的 配置 具有 更 高 优先 级 。 

* 使 用 @WebServlet 注解 定义 Servlet， 要 使 用 描述 符 和 覆盖 其 值 ， 描述 符 中 的 servlet 名 字 必 须 匹 配 使 用 注解 
指定 的 Servlet 名 字 (明确 指定 或 如 果 注 解 没有 指定 则 是 默认 名 字 ) 。 

* 使 用 注解 定义 的 Servlet 和 Filter 初 始 化 参数 ， 如 果 描 述 符 中 的 初始 化 参数 的 名 字 完 全 匹配 指定 在 注解 中 的 名 
字 ， 则 将 被 描述 符 中 的 覆盖 。 初 始 化 参数 在 注解 和 描述 符 之 间 是 可 添加 的 。 

* Url-pattern， 当 以 给 定 servlet 名 字 指 定 在 描述 符 中 时 ， 将 覆盖 注解 指定 的 Url pattern » 

* 使 用 @WebFilter 注解 定义 的 FiLter， 要 使 用 描述 符 履 盖 其 值 ， 描 述 符 中 的 FilLter 名 字 必 须 匹配 使 用 注解 指 
定 的 Filter 名 字 (明确 指定 或 如 果 注 解 没 有 指定 则 是 默认 名 字 ) o 

* Filter 应 用 的 url-pattern， 当 以 给 定 Filter 名 字 指 定 在 描述 符 中 时 ， 将 覆盖 注解 指定 的 url pattern e 

* Filter 应 用 的 DispatcherType， 当 以 给 定 FilLter 名 字 指定 在 描述 符 中 时 ， 将 履 盖 注解 指定 的 DispatcherT 
ype ° 

* 下 面 的 例子 演示 了 上 面 的 一 些 规则 : 


使 用 注解 声明 Servlet 和 在 打包 到 的 相应 web.xml 描 述 符 中 声明 Servlet : 


QWebServlet(urlPatterns="/MyPattern", initParams= 
{@WebInitParam(name="ccc", value="333")}) 
public class com.acme.Foo extends HttpServlet 


{ 
} 
web.xml 
<servlet> 
<servlet-class>com.acme.Foo</servlet-class> 
<servlet -name>Foo</servlet -name> 
<init -param> 
<param-name>aaa</param-name> 
<param-value>111</param-value> 
</init -param> 
</servlet> 
<servlet> 
<servlet-class>com.acme.Foo</servlet-class> 
<servlet -name>Fum</servlet -name> 
<init-param> 
<param-name>bbb</param-name> 
<param-value>222</param-value> 
</init -param> 
</servlet> 


<servlet -mapping> 
<servlet -name>Foo</servlet -name> 
<url-pattern>/foo/*</url-pattern> 
</servlet -mapping> 
<servlet -mapping> 
<servlet -name>Fum</servlet -name> 
<url-pattern>/fum/*</url-pattern> 
</servlet -mapping> 


为 使 用 注解 声明 的 Servlet 名 字 不 匹配 在 web.xml 中 声明 的 servlet 名 字 ， 在 web.xml 中 除 
了 其 他 的 声明 外 ， 注 解 指 定 一 个 新 的 servlet 声明 ， 相 当 于 : 


<servlet> 
<servlet-class>com.acme.Foo</servlet-class> 
<servlet-name>com.acme.Foo</servlet -name> 
<init-param> 
<param-name>ccc</param-name> 
<param-value>333</param-name> 
</servlet> 


如 果 上 面 的 web.xml 被 替换 为 如 下 : 


<servlet> 
<servlet-class>com.acme.Foo</servlet-class> 
<servlet-name>com.acme.Foo</servlet -name> 
<init-param> 
<param-name>aaa</param-name> 
<param-value>111</param-value> 
</init-param> 
</servlet> 
<servlet-mapping> 
<servlet-name>com.acme.Foo</servlet-name> 
<url-pattern>/foo/*</url-pattern> 


</servlet -mapping> 


那么 有 效 的 描述 符 将 等 价 于 : 


<servlet-class>com.acme.Foo</servlet-class> 
<servlet -name>com.acme.Foo</servlet -name> 
<init-param> 
<param-name>aaa</param-name> 
<param-value>111</param-value> 
</init -param> 
<init-param> 
<param-name>ccc</param-name> 
<param-value>333</param-value> 
</init-param> 
</servlet> 
<servlet-mapping> 
<servlet-name>com.acme.Foo</servlet-name> 
<url-pattern>/foo/*</url-pattern> 
</servlet -mapping> 


共享 库 / 运行 时 可 插 拔 性 


除了 支持 fragment 和 使 用 注解 的 外 ， 要 求 之 一 是 我 们 不 仅 能 plug-in F< 4 WEB-INF/lib F ty > 
也 能 plugin 框 架 共 享 副本 一 包括 能 plug-in 到 容器 的 如 建议 在 web 容 器 之 上 的 JAX-WS、JAX-RS 
和 JSF。 ServletContainerlnitializer 人 允许 处 理 这 样 的 使 用 情况 下 ， 如 下 所 述 。 
ServletContainerlnitializer 类 通过 jar services API 查 找 。 对 于 每 一 个 应 用 ， 应 用 局 动 时 ， 由 容 
器 创建 一 个 ServletContainerlnitializer 实 例 。 框 架 提 供 的 ServletContainerlnitializer 实 现 必 须 绑 
定 在 jar 包 的 META-INF/services 目 录 中 的 一 个 叫做 javax.servlet.ServletContainerlnitializer 的 文 
件 ， 根 据 jar services API， 指 定 ServletContainerlnitializer 的 实现 。 


除 ServletContainerlnitializer 外 ， 我 们 还 有 一 个 注解 一 HandlesTypes。 在 
ServletContainerlnitializer 实现 上 的 HandlesTypes 注 解 用 于 表示 感 兴趣 的 一 些 类 ， 它 们 可 能 
指定 了 HandlesTypes 的 value 中 的 注解 (类 型 、 方 法 或 自动 级 别 的 注解 ) ， 或 者 是 其 类 型 的 超 
类 继承 /实现 了 这 些 类 之 一 。 无 论 是 否 设置 了 metadata-complete，HandlesTypes 注 解 将 应 

用 。 


当 检 测 一 个 应 用 的 类 看 是 否 它 们 匹配 ServletContainerlnitializer 的 HandlesTypes 指 定 的 条 件 
时 ， 如 果 应 用 的 一 个 或 多 个 可 选 的 JAR 包 缺失 ， 容 器 可 能 遇 到 类 装载 问题 。 由 于 容器 不 能 决定 
是 否 这 些 a 3 用 正常 工作 ， 它 必须 忽略 它们 ， 同 时 也 提供 一 个 将 记录 
它们 的 配置 选项 。 


如 果 ServletContainerlnitializer 实 现 没有 @HandlesTypes 注 解 ， 或 如 果 没 有 匹配 任何 指定 的 
HandlesType， 那 么 它 会 为 每 个 应 用 使 用 null 值 的 集合 调用 一 次 。 这 将 允许 initializer 基 于 应 用 
中 可 用 的 资源 决定 是 否 需要 初始 化 Servlet/Filter 。 


在 任何 Servlet Listener 的 事件 被 触发 之 前 ， 当 应 用 正在 启动 时 ，ServletContainerlnitializer 的 
onStartup 方 法 将 被 调用 。 ServletContainerlnitializer's 的 onStartup 得 到 一 个 类 的 Set， 其 或 者 
继承 /实现 initializer 表 示 感 兴趣 的 类 ， 或 者 它 是 使 用 指定 在 @HandlesTypes 注 解 中 的 任意 类 注 
解 的 。 


下 面 一 个 具体 的 例子 展示 了 这 是 如 何 工作 的 。 
让 我 们 学 习 JAX-WS web service 运行 时 。 


JAX-WS 运行 时 实现 通常 不 是 绑 定 到 每 个 war 包 。 其 实现 将 绑 定 一 个 
ServletContainerlnitializer 的 实现 (如 下 所 示 ) 且 容 器 将 查找 使 用 的 services API ( 绑 定 在 jar 
包 中 的 META-INF/services 目录 中 的 一 个 叫做 javax.servlet.ServletContainerlnitializer 的 文 
件 ， 它 将 指出 如 下 所 示 的 JAXWSServletContainerlnitializer) ° 


@HandlesTypes(WebService.class) 
JAXWSServletContainerInitializer 
implements ServletContainerInitializer 


{ 
public void onStartup(Set<Class<?>> c, ServletContext ctx) 
throws ServletException { 
// JAX-WS specific code here to initialize the runtime 
// and setup the mapping etc. 
ServletRegistration reg = ctx.addServlet("JAXWSServlet", 
"com.sun.webservice. JAXwWSServlet"); 
reg.addServletMapping("/foo"); 


ERA jar 包 也 可 能 被 绑 定 到 War 包 目 录 中 的 WEB-INF/lib 目录 。 如 果 
ServletContainerlnitializer 被 绑 定 到 应 用 的 WEB-INF/lib 目录 内 的 一 个 JAR 包 中 ， 它 的 
onStartup 方法 在 绑 定 到 的 应 用 局 动 期 间 将 被 仅 调 用 一 次 。 如 果 ， 相 反 ， 
ServletContainerlnitialzer 被 绑 定 到 WEB-INF/lib 目录 外 的 一 个 JAR 包 中 ， 但 仍 能 被 运行 时 的 
服务 提供 商 查找 机 制 发 现时 ， 每 次 启动 应 用 时 ， 它 的 onStartup 方法 将 被 调用 。 


ServletContainerlnitializer 接口 的 实现 将 被 运行 时 的 服务 查找 机 制 或 语义 上 与 它 等 价 的 容器 特 
定 机 制 发 现 。 在 任 一 种 情况 ，web fragment JAR 包 的 ServletContainerlnitializer AR 务 被 排除 


于 一 个 absolute ordering 必须 被 忽略 ， 这 些 服务 被 发 现 的 顺序 必须 遵照 应 用 的 类 装载 委托 模 
型 。 


可 插 拔 性 
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ServletContainerlnitializer 和 编程 式 注 册 特 性 可 以 在 Servlet 和 JSP 容器 之 间 提 供 一 个 清晰 的 
职责 分 离 ， 通 过 由 Servlet 容器 只 负责 解析 web.xml 和 web-fragment.xml 资源 ， 而 解析 标签 
库 描 述 符 (TLD) 资源 委托 给 ISP 容器 。 


ZEZA > web 容器 必须 扫描 TLD 资源 寻找 任何 Listener 声明 。 使 用 Servlet 3.0 和 后 续 版 本 
后 ， 该 职责 可 以 委托 给 JSP 容器 。JSP GEXA KA —* Servlet3.0 兼容 的 Servlet 容器 

中 ， 可 以 提供 它 自己 的 ServletContainerlnitializer 实现 ， 搜 索 传 递 到 它 的 onStartup 方法 的 
ServletContext 参数 寻找 任何 TLD 资源 ， 扫 描 这 些 资源 寻找 Listener 声明 ， 并 向 
ServletContext 注册 相关 的 Listener ° 


另外 ，Servlet3.0 之 前 ，JSP 容器 用 于 必须 扫描 应 用 的 部 署 描述 符 寻 找 jsp-config 相关 的 配 
置 。 使 用 Servlet3.0 和 后 续 版 本 后 ，Servlet 容器 必须 提供 通过 
ServletContext.getJspConfigDescriptor 方法 得 到 应 用 的 web.xml 和 web-fragment.xml 部 署 
wat AFP ATE jsp-config 相关 的 配置 。 


在 TLD 中 发 现 的 和 编程 注册 的 任何 ServletContextListener 在 它们 提供 的 功能 上 是 有 限 的 。 
任何 试图 调用 一 个 在 Servlet3.0 中 加 入 的 ServletContext API 方法 将 导致 一 个 
UnsupportedOperationException ° 


另外 ，Servlet 3.0 和 后 续 版 本 兼容 的 Servlet 容器 必须 提供 一 个 名 字 为 
javax.servlet.context.orderedLibs 的 ServletContext 属性 ， 它 的 值 (java.util.List 类 型 ) 包含 
了 由 ServletContext 所 代表 的 应 用 的 WEB-INF/lib 目录 中 的 JAR 文件 的 名 字 列 表 ， 按 照 它们 
的 web fragment 名 字 的 排序 (可 能 排除 如 果 fragment JAR 包 已 经 被 排除 在 absolute- 
ordering) ， 或 者 null 如 果 应 用 没有 指定 任意 绝对 或 相对 顺序 。 


处 理 注 解 和 fragment 


Web 应 用 可 同时 包括 注解 和 web.xml/web-fragment.xml 部 署 描述 符 。 如 果 没 有 部 署 描述 符 ， 
或 有 一 个 但 其 metadata-complete 没有 设置 为 true，web.xml、web-fragment 和 注解 如 果 在 应 
用 中 使 用 则 必须 被 处 理 。 下 表 描 述 了 是 否 处 理 注 解 和 web.xml 的 fragment 。 


TABLE 8-1 Annotations and web fragment processing requirements 


部 署 描述 符 metadata-complete 处 理 注 解 和 web fragment 
web.xml 2.5 yes no 
web.xml 2.5 no yes 
web.xml 3.0 或 后 来 的 yes no 


Web.xml 3.0 或 后 来 的 no yes 


分 发 请 来 


构建 Web 应 用 时 ， 把 请 求 转发 给 另 一 个 servlet 处 理 、 或 在 请 求 中 包含 另 一 个 servlet 的 输出 
通常 是 很 有 用 的 。RequestDispatcher 接口 提供 了 一 种 机 制 来 实现 这 种 功能 。 


当 请 求 启用 异步 处 理 时 ，AsyncContext 允许 用 户 将 这 个 请 求 转发 到 servlet 容器 。 


获取 RequestDispatcher 


实现 了 RequestDispatcher 接口 的 对 象 ， 可 以 从 ServietContext 中 的 下 面 方法 得 到 : 


e getRequestDispatcher 
e getNamedDispatcher 


getRequestDispatcher 方法 需要 一 个 String 类 型 的 参数 描述 在 ServletContext 作用 域内 的 路 
径 。 这 个 路 径 必 须 是 相对 于 ServletContext 的 根 路 径 ， 或 以 /开头 ， 或 者 为 空 。 该 方法 根据 这 
个 路 径 使 用 servlet 路 径 匹配 规则 ( 见 第 12 章 ， 请 求 映射 到 servlet) 来 查找 servlet， 把 它 包 

装 成 RequestDispatcher 对 象 并 返回 。 如 果 基 于 给 定 的 路 径 没有 找到 相应 的 servlet > PAR 
回 这 个 路 径 内 容 提 供 的 RequestDispatcher 。 


getNamedDispatcher 方法 使 用 一 个 ServletContext 知道 的 servlet 名 称 作为 参数 。 如 果 找 到 
一 个 servlet， 则 把 它 包 装 成 RequestDispatcher 对 象 ， 并 返回 该 对 象 。 如 果 没 有 与 给 定名 字 
相关 的 servlet， 该 方法 必须 返回 null 。 


为 了 让 RequestDispatcher 对 象 使 用 相对 于 当前 请 求 路 径 的 相对 路 径 (不 是 相对 于 
ServletContext 根 路 径 ) 获得 一 个 servlet， 在 ServletRequest 接口 中 提供 了 
getRequestDispatcher 方法 。 


此 方法 的 行为 与 ServletContext 中 同名 的 方法 相似 。Servlet 容器 根据 request 对 象 中 的 信息 
把 给 定 的 相对 路 径 转 换 成 当前 servlet 的 完整 路 径 。 例 如 ， 在 以 /作为 上 下 文 根 路 径 和 请 求 路 
径 /garden/tools.html 中 ， 通 过 ServletRequest.getRequestDispatcher("header.html") 获得 的 
请 求 调度 器 和 通过 调用 ServletContext.getRequestDispatcher("/garden/header.html") 获得 的 
完全 一 样 。 


请 求 调度 器 路 径 中 的 查询 字符 串 


ServletContext 和 ServietRequest 中 创建 RequestDispatcher 对 象 的 方法 使 用 的 路 径 信 息 中 
允许 附加 可 选 的 查询 字符 串 信 息 。 比 如 ， 开 发 人 员 可 以 通过 下 面 的 代码 来 获得 一 个 
RequestDispatcher : 


String path = “/raisins.jsp?orderno=5” ; 
RequestDispatcher rd = context.getRequestDispatcher (path); 
rd.include(request, response); 


查询 字符 串 中 指定 的 用 来 创建 RequestDispatcher 的 参数 优先 于 传递 给 
其 他 同名 参数 。 与 RequestDispatcher 相关 的 参数 作用 域 仅 适 用 于 包含 
(forward) 调用 期 间 。 


它 包 含 的 servlet 中 的 
(include) 或 转发 
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使 用 请 求 调度 器 


要 使 用 请 求 调度 器 ，servlet 可 调用 RequestDispatcher 接口 的 include 或 forward 方法 。 这 些 
方法 的 参数 既 可 以 是 javax.servlet.Servlet 接口 的 service 方法 传 来 的 请 求 和 响应 对 象 实例 ， 
也 可 以 是 本 规范 的 2.3 版 本 中 介绍 的 请 求 和 响应 包装 器 类 的 子 类 对 象 实例 。 对 于 后 者 ， 包 装 器 
实例 必须 包装 容器 传递 到 service 方法 中 的 请 求 和 响应 对 象 。 


容器 提供 者 应 该 保证 分 发 到 目标 servlet 的 请 求 作为 原始 请 求 发 生 在 的 同一 个 JVM 的 同一 个 
线程 中 。 


Include 方法 


RequestDispatcher 接口 的 include 方法 可 以 随时 被 调用 。|nclude 方法 的 目标 servlet 能 够 访 
问 请 求 对 象 的 各 个 方法 (all aspects) ， 但 是 使 用 响应 对 象 的 方法 会 受到 更 多 限制 。 


ay 


只 能 把 信息 写 到 响应 对 象 的 ServletOutputStream 或 Writer 中 ， 或 提交 在 最 后 写 保 留 在 响 
缓冲 区 中 的 内 容 ， 或 通过 显 式 地 调用 ServletResponse 接口 的 flushBuffer 方法 。 它 不 能 设 
置 响应 头 部 信息 或 调用 任何 影响 响应 头 部 信息 的 方法 ，HttpServletRequest.getSession() 和 
HttpServletRequest.getSession(boolean) 方法 除外 。 任 何 试 图 设置 头 部 信息 必须 被 忽略 ， 任 
何 调用 HttpServletRequest.getSession() PR eh 方法 将 

需要 添加 一 个 Cookie 响应 头 部 信息 ， 如 果 响 应 已 经 提交 ， 人 必须 抛 出 一 个 IllegalStateException 
异常 。 


N 


to R RUKI servlet = RequestDispatch.include() 的 目标 servlet， 而 且 请 求 的 资源 不 存在 ， 那 
么 默认 的 servlet 必须 抛 出 FileNotFoundException 异常 。 如 果 这 个 异常 没有 被 捕获 和 处 理 ， 
以 及 响应 还 未 提交 ， 则 响应 状态 码 必须 被 设置 为 500。 


置 请 求 参数 


除了 用 getNamedDispatcher 方法 获得 的 servlets 外 ， 被 别 的 servlet 使 用 RequestDispatcher 
的 include 方 法 调用 过 的 servlet， 有 权 访 问 调用 者 的 servlet 的 路 径 。 以 下 的 请 求 属性 必须 被 设 
a 


javax.servlet.include.request_uri 
javax.servlet.include.context_path 
javax.servlet.include.servlet_path 
javax.servlet.include.path_info 
javax.servlet.include.query_string 


这 些 属性 可 以 通过 和 包含 的 servlet 的 请 求 对 象 的 getAttribute 方法 访问 ， 它 们 的 值 必 须 分 别 与 
被 包含 servlet 的 请 求 URI、 上 下 文 路 径 、servlet 路 径 、 路 径 信 息 、 查 询 字 符 串 相等 。 如 果 随 
的 请 求 包含 这 些 属 性 ， 那 么 这 些 属性 会 被 后 面包 含 的 属性 值 替换 。 


Ea 


to R EAK servlet 通过 getNamedDispatcher 方法 获得 ， 那 么 这 些 属性 不 能 被 设置 。 


Forward 方法 


RequestDispatcher 接口 的 forward 方法 ， 只 有 在 没有 输出 提交 到 向 客户 端 时 ， 通 过 正在 被 调 
用 的 servlet 调用 。 如 果 响 应 缓冲 区 中 存在 尚未 提交 的 输出 数据 ， 这 些 数据 内 容 必 须 在 目标 
servlet 的 service 方法 调用 前 清除 。 如 果 响 应 已 经 提交 ， 必 须 抛 出 一 个 lllegalStateException 
异常 。 


请 求 对 象 暴露 给 目标 servlet 的 路 径 元 素 (path elements) 必须 反映 获得 RequestDispatcher 
使 用 的 路 径 。 


see | 外 的 是 ， 如 果 RequestDispatcher 是 通过 getNamedDispatcher 方 法 获得 。 这 种 情况 
， 请求 对 象 的 路 径 元 素 必须 反映 这 些 原始 请 求 。 在 RequestDispatcher 接口 的 forward 方 
常 返回 之 前 ， 响 应 的 内 容 必 须 被 发 送 和 提交 ， 且 由 Servlet 容器 关闭 ， 除 非 请 求 处 于 异 
PER 。 如 果 RequestDispatcher.forward() 的 目标 发 生 错误 ， 异 常 信息 会 传 回 所 有 调用 它 经 
过 的 过 滤器 和 servlet， 且 最 终 传 回 给 容器 。 


查询 字符 串 


在 转发 或 包含 请 求 时 请 求 调 度 机 制 负责 聚集 (aggregating) 查询 字符 串 参 数 。 


转发 的 请 求 参 数 


除了 可 以 用 getNamedDispatcher 方法 获得 servlet 外 ， 已 经 被 另 一 个 servlet 使 用 
RequestDispatcher 的 forward 方法 调用 过 的 servlet， 有 权 访 问 被 调用 过 的 servlet 的 路 径 。 
以 下 的 请 求 属性 必须 设置 : 


javax.servlet.forward.request_uri 
javax.servlet.forward.context_path 
javax.servlet.forward.servlet_path 
javax.servlet.forward.path_info 
javax.servlet.forward.query_string 


这 些 属性 的 值 必须 分 别 与 HttpServletRequest 的 getRequestURI, ` getContextPathi ` 
getServletPath ` getPathInfo ` getQueryString 方法 的 返回 值 相 等 ， 这 些 方法 在 从 客户 端 接收 
到 的 请 求 对 象 上 调用 ， 值 传递 给 调用 链 中 的 第 一 个 servlet 对 象 。 


这 些 属 


些 前 过 转发 Servlet 的 请 求 对 象 的 getAttribut 方法 访问 。 请 注意 ， 即 使 在 多 个 转发 和 相 
继 的 包 


性 通 
包含 (subsequent includes) 被 调用 的 情况 下 ， 这 些 属性 必须 始终 反映 原始 请 求 中 的 信 


[四 og 


如 果 转 发 的 servlet 使 用 getNamedDispatcher 方法 获得 ， 这 些 属 性 必须 不 能 被 设置 。 


| 
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错误 处 理 


如 果 请 求 分 发 的 目标 servlet 抛 出 运行 时 异常 或 受 检查 类 型 异常 ServletException 或 
IOException， 弄 常 应 该 传播 到 调用 的 servlet。 所 有 其 它 的 异常 都 应 该 被 包装 成 
ServletExceptions， 异 常 的 根本 原因 设置 成 原来 的 异常 ， 因 为 它 不 应 该 被 传播 。 


获取 AsyncContext 


实现 了 AsyncContext 接口 的 对 象 可 从 ServletRequest 的 一 个 startAsync 方法 中 获得 ， 一 旦 
有 了 AsyncContext 对 象 ， 你 就 能 够 使 用 它 的 complete() 方法 来 完成 请 求 处 理 ， 或 使 用 下 面 
描述 的 转发 方法 。 


Dispatch 方法 


可 以 使 用 AsyncContext 中 下 面 的 方法 来 转发 请 求 : 
dispatch(path) 


这 个 dispatch 方法 的 String 参数 描述 了 一 个 在 ServletContext 作用 域 中 的 路 径 。 这 个 路 径 必 
须 是 相对 于 ServletContext 的 根 路 径 并 以 开头 。 


dispatch(servletContext, path) 


这 个 dispatch 方法 的 String 参数 描述 了 一 个 在 ServletContext 指定 作用 域 中 的 路 径 。 这 个 路 
径 必须 是 相对 于 ServietContext 的 根 路 径 并 以 /开头 。 


dispatch() 


这 个 方法 没有 参数 ， 它 使 用 原来 的 URI 路 径 。 如 果 AsyncContext 已 经 通过 
startAsync(ServletRequest, ServletResponse) 初始 化 ， 且 传递 过 来 的 请 求 是 
HttpServletRequest 的 实例 ， 那 么 这 个 请 求 分 发 到 HttpServletRequest.getRequestURI() 返回 
的 URI。 和 否则 转发 到 容器 最 后 一 次 转发 的 URI © 


AsyncContext 接口 中 的 dispatch 方法 可 被 等 待 异 步 事 件 发 生 的 应 用 程序 调用 。 如 果 
AsyncContext 已 经 调用 了 complete() 方法 ， 必 须 抛 出 llegalStateException 异常 。 所 有 不 同 
的 dispatch 方法 会 立即 返回 并 且 不 会 提交 响应 。 


请 求 对 象 暴 露 给 目标 servlet 的 路 径 元 素 (path elements) 必须 反映 AsyncContext.dispatch 
中 指定 的 路 径 


查询 字符 串 


请 青 求 调度 度 机 制 是 在 调度 度 请 青 求 时 负责 TR (aggregating) 查询 字符 串 


调度 请 求 参数 


使 用 AsyncContext 的 dispatch 方法 调用 过 的 servlet 能 够 访问 原始 请 求 的 路 径 。 下 面 的 
request 属 性 必须 设置 : 


javax.servlet.async.request_uri 
javax.servlet.async.context_path 
javax.servlet.async.servlet_path 
javax.servlet.async.path_info 
javax.servlet.async.query_string 


这 些 属 性 的 值 必 须 分 别 与 HttpServletRequest 的 getRequestURI ` getContextPath ` 
getServletPath、getPathlnfo、getQueryString 方法 的 返回 值 相等 ， 这 些 方法 在 从 客户 端 接收 
到 的 请 求 对 象 上 调用 ， 值 传递 给 调用 链 中 的 第 一 个 servlet 对 象 。 


这 些 属 性 都 可 以 从 分 发 的 servlet 通过 请 求 对 象 的 getAttribute 方法 获得 。 注 意 ,这 些 属性 必须 
反映 原始 请 求 中 的 信息 ， 甚 至 是 多 个 分 发 的 情况 。 


Web 应 用 


Web 应 用 是 一 个 servlets,HTML 页 面 ,类 ,和 其 他 资源 的 集合 ， 用 于 一 个 在 Web 服务 器 的 完成 
的 应 用 。Web 应 用 可 以 捆绑 和 运行 来 自 多 个 供应 商 的 在 多 个 容器 。 


Web 服务 器 中 的 Web 应 用 


在 Web 服务 器 中 Web 应 用 程序 的 根 目录 是 一 个 特定 的 路 径 。 例 如 ， 一 个 catalog 应 用 ， 可 以 
位 于 http://www.mycorp.com/catalog。 以 这 个 前 级 开始 的 所 有 请 求 将 被 路 由 到 代表 catalog 应 
用 的 ServletContext 环境 中 。 


servlet 容器 能 够 制定 Web 应 用 程序 自动 生成 的 规则 。 例 如 ， 一 个 ~user/ 映 射 可 用 于 映射 到 一 
个 基于 /home /user/public_html/ 的 Web Ez M ° 


默认 情况 下 ， 在 任何 时 候 一 个 Web 应 用 程序 的 实例 必须 运行 在 一 个 虚拟 机 (VM) 中 。 如 果 
应 用 程序 通过 其 部 署 描述 文件 标记 为 “分 布 式 的， 那么 可 以 覆盖 此 行为 。 标 记 为 分 布 式 的 应 用 
程序 必须 遵守 比 普通 的 Web 应 用 程序 更 严格 的 规则 。 本 规范 中 陈述 了 这 些 规则 。 


5 ServletContext 的 关系 


servlet 容器 必须 强制 Web 应 用 程序 和 ServletContext 之 间 一 对 一 对 应 的 关系 。 
ServletContext 对 象 提 供 了 一 个 servlet 和 它 的 应 用 程序 视图 。 


Web 应 用 的 元 素 


Web 应 用 可 能 由 下 面 几 部 分 组 成 : 


e Servlet 

e JSP™ 页 面 

e 工具 类 

。 静态 文档 (HTML, 图 片 , 声音 , FF.) 
* ZP Java applet, bean, 和 类 

o 结合 上 述 所 有 要 素 的 描述 性 的 元 信息 


部 署 层次 结构 


本 规范 定义 了 一 个 用 于 部 署 和 打包 用 途 的 ， 可 存在 于 开放 文件 系统 、 归 档 文件 或 一 些 其 他 形 
式 中 的 层次 结构 。 建 议 servlet 容器 支持 这 种 结构 作为 运行 时 表示 形式 ， 但 不 是 必须 的 . 


目录 结构 


一 个 Web 应 用 程序 以 结构 化 的 目录 层次 结构 存在 。 层 次 结构 的 根 目 录 作 为 文件 的 归档 目录 ， 
这 些 文件 是 应 用 的 一 部 分 。 例 如 ， 对 于 Web 容器 中 一 个 Web 应 用 程序 的 上 下 文 路 

径 /catalog， 在 Web 应 用 程序 层次 结构 中 的 index.html 文件 ， 或 在 WEB-INF/lib 目录 下 的 
JAR 文件 中 的 META-INF/resources 目录 下 包括 的 index.html 文件 ， 可 以 满足 从 
/catalog/index.html 送 达 的 请 求 。 如 果 在 根 上 下 文中 和 应 用 的 WEB-INF/lib 目录 下 的 JAR 文件 
中 的 META-INF/resources 目录 中 都 存在 一 个 index.html 文件 ， 那么 必须 使 用 根 上 下 文中 的 
index.html。 匹 配 的 URL 到 上 下 文 路 径 的 规则 安排 在 第 12 章 :“ 请 求 映射 到 servlet" 中 。 由 于 应 
用 的 上 下 文 路 径 确 定 了 Web 应 用 内 容 的 URL 命名 空间 ，Web 容 器 必须 拒绝 Web 应 用 定义 的 
上 下 文 路 径 ， 因 为 可 能 在 这 个 URL 命名 空间 中 导致 潜在 的 冲突 。 例 如 ， 试 图 部 署 两 个 具有 相 
同上 下 文 路 径 的 Web 应 用 时 可 能 发 生 这 种 情况 。 由 于 把 请 求 匹 配 到 资源 是 区 分 大 小 写 的 ， 所 
以 在 确定 潜在 冲突 时 也 必须 区 分 大 小 写 。 


应 用 程序 层次 结构 中 存在 一 个 名 为 ”WEB-INF” 的 特殊 目录 。 这 个 目录 包含 了 与 应 用 程序 相关 的 
所 有 东西 ， 这 些 东西 不 在 应 用 程序 的 归档 目录 中 。 大 多 数 WEB-INF 节点 都 不 是 应 用 程序 公共 
文档 树 的 一 部 分 。 除 了 WEB-INF/lib 目录 下 打包 在 JAR 文件 中 META-INF/resources 目录 下 
的 静态 资源 和 ISP 文件 之 外 ，WEB-INF 目录 下 包含 的 其 他 任何 文件 都 不 能 由 容器 直接 提供 给 
客户 端 访问 。 然 而 ，WEB-INF 目录 中 的 内 容 可 以 通过 servlet 代 码 调用 ServletContext 的 
getResource 和 getResourceAsStream 方 法 来 访问 ， 并 可 使 用 RequestDispatcher 调用 公开 
这 些 内 容 。 因 此 ， 如 果 应 用 开发 人 员 想 通过 servlet 代码 访问 这 些 内 容 ， 而 不 愿意 直接 对 客户 
端 公开 应 用 程序 指定 配置 信息 ， 那 么 可 以 把 它 放 在 这 个 目录 下 。 由 于 把 请 求 匹 配 到 资源 的 映 
射 区 分 大 小 写 ， 例 如 ， 客 户 端 请 求 /WEB-INF/foo’，‘/WEb-iNf/foo'， 不 应 该 返回 位 于 /WEB- 
INF 下 的 Web 应 用 程序 的 内 容 ， 也 不 应 该 返回 其 中 任何 形式 的 目录 列表 。 


WEB-INF 目 录 中 的 内 容 有 : 


e /WEB-INF/web.xml 部 署 描述 文件 。 

e servlet 和 实用 工具 类 目录 /WEB-INF/classes/。 此 目录 中 的 类 对 应 用 程序 类 加 载 器 必须 是 
可 见 的 。 

e java 归档 文件 区 域 /WEB-INF/lib/*.jar。 这 些 文件 中 包括 了 servlet，bean > af & a IR Fe AT 
包 在 JAR 文 件 中 的 JSP 文件 ， 以 及 其 他 对 Web 应 用 程序 有 用 的 实用 工具 类 。Web 应 用 程 
序 的 类 加 载 器 必须 能 够 从 这 些 归档 文件 中 加 载 类 。 


Web 应 用 程序 类 加 载 器 必须 先 从 WEB-INF/classes 目录 下 加 载 类 ， 然 后 从 WEB-INF/lib 目录 
下 的 JAR 库 中 加 载 。 此 外 ， 除 了 静态 资源 打包 在 JAR 文件 中 的 情况 外 ， 任 何 来 自 客户 端的 请 
求 访问 WEB-INF/ 目 录 中 的 资源 必须 返回 一 个 SC_NOT_FOUND (404) 的 响应 。 


应 用 程序 目录 结构 示例 


下 面 是 一 个 示例 Web 应 用 程序 的 文件 清单 : 


/index. html 

/howto.jsp 

/feedback. jsp 

/images/banner . gif 

/images/jumping. gif 

/WEB- INF/web. xml 

/WEB-INF/1ib/jspbean. jar 
/WEB-INF/1ib/catalog. jar! /META-INF/resources/catalog/moreOffers/books. html 
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class 
/WEB-INF/classes/com/mycorp/util/MyUtils.class 


Web 应 用 归档 文件 


可 以 使 用 标准 的 Java 归档 工具 把 Web 应 用 程序 打包 并 签名 到 一 个 Web 存档 格式 (WAR) 
文件 中 。 例 如 ， 一 个 关于 "issue tracking” 的 应 用 程序 可 以 分 布 在 一 个 称 为 issuetrack.war 的 归 
档 文 件 中 。 


当 打 包 成 这 种 形式 时 ， 将 生成 一 个 META-INF 目录 ， 其 中 包含 了 对 java 归档 工具 有 用 的 信 
息 。 尽 管 这 个 目录 的 内 容 可 以 通过 serviet 代码 调用 ServletContext 的 getResource 和 
getResourceAsStream 方法 来 访问 ， 容 器 也 不 能 把 这 个 目录 当 作 内 容 来 响应 客户 端 请 求 。 此 
外 ， 任 何 请 求 访问 META-INF 目录 中 的 资源 必须 返回 一 个 SC_NOT_FOUND (404) 的 响 
KEL oo 


Web 应 用 部 署 描述 符 


Web 应 用 程序 部 署 描述 文件 ( 见 第 14 章 ，“ 部 署 描述 文件 ") 的 配置 和 部 署 信息 包括 以 下 几 种 


类 型 : 


* ServletContext 的 初始 化 参数 
e Session 配置 

e Serviet/JSP 的 定义 

e Servlet/JSP 的 映射 

* MIME 类 型 映射 

. 欢迎 文件 列表 

e. 错误 页 面 

e 安全 


扩展 的 依赖 关系 


ee ey 通常 将 它们 安装 在 容器 的 库 文件 中 。 这 些 文件 往往 

通用 的 或 标准 的 API， 可 以 在 不 牺牲 可 移植 性 的 情况 下 使 用 。 仅 由 一 个 或 几 个 应 用 程序 使 用 
ae Web 应 用 程序 的 一 部 分 来 访问 。 容 器 必须 为 这 iki ii 录 。 放 置 在 这 个 
目录 中 的 文件 必须 对 所 有 的 Web 应 用 可 见 。 此 目录 的 位 置 由 容器 指定 。servlet 容器 用 于 加 载 
这 些 库 文件 的 类 加 载 器 必须 和 在 同一 个 JVM 中 的 所 有 Web 应 用 的 类 加 载 器 相同 。 这 个 类 加 
载 器 的 实例 必须 在 Web 应 用 程序 类 加 载 器 的 父 类 加 载 器 链 中 。 


为 了 保持 可 移植 性 ， 应 用 程序 开发 人 员 需 要 知道 Web 容器 中 安装 了 哪些 扩展 ， 而 容器 需要 知 
道 WAR 中 的 servlet 依赖 哪些 库 。 


依赖 这 样 的 扩展 的 应 用 开发 人 员 必 须 在 WAR 文件 中 提供 一 个 列 出 所 有 WAR 文件 所 需 扩 展 的 
META-INF/MANIFEST.MF 文件 。 清 单 文件 的 格式 应 该 遵循 标准 的 JAR 清单 格式 。 在 部 署 
Web 应 用 程序 的 时 候 ，Web 容 器 必须 使 正确 的 扩展 版 本 对 遵循 可 选 包 版 本 控制 ( Optional 
Package Versioning) 机 制 (http://java.sun.com/j2se/1.4/docs/guide/extensions/) 定义 的 规 
则 的 应 用 程序 可 见 。 


Web 容器 也 必须 能 够 识别 出 WAR 文件 中 WEB-INF/lib 目录 下 的 任意 一 个 JAR 包 中 的 清单 文 
件 声明 的 依赖 关系 。 


如 果 Web 容器 不 能 够 满足 以 这 种 方式 声明 的 依赖 关系 ， 它 应 该 使 用 一 条 有 意义 的 错误 消息 拒 
绝 该 应 用 程序 。 


Web 应 用 程序 类 加 载 器 


容器 | 于 加 载 WAR 文件 中 servlet 的 类 加 载 器 必须 允许 开发 人 员 使 用 getResource 加 载 遵循 
常 JavaSE 语义 的 WAR 文件 的 JAR 包 中 包含 的 任何 资源 。 和 Java EE 许可 协议 中 描述 的 

a 不 属于 Java EE a 的 servlet 容器 不 应 该 允许 应 用 程序 覆盖 Java SE 平台 中 的 类 ， 
如 在 java. 和 javax. 命名 空间 中 的 类 ，Java SE 不 允许 进行 修改 。 容 器 不 应 该 允许 应 用 程序 禾 

盖 或 访问 容器 的 cee 。 同 时 建议 应 用 程序 类 加 载 器 实现 成 WAR 文件 中 的 类 和 资源 优先 于 属 

容器 范围 内 的 JAR 包 中 的 类 和 资源 加 载 。 一 个 类 加 载 器 的 实现 必须 保证 对 部 署 到 容器 的 每 
个 web 应用， 调用 Thread.currentThread.getContextClassLoader() 返回 一 个 实现 了 本 节 规 
定 的 约定 的 ClassLoader 实例 。 此 外 ， 部 署 的 每 个 Web 应 用 程序 的 ClassLoader 实例 必须 是 
一 个 单独 的 实例 。 容 器 必须 在 任何 回调 (包括 侦 听 器 回调 ) 到 Web 应 用 程序 之 前 设置 上 面 描 
述 的 线程 上 下 文 ClassLoader ， 一 旦 回调 返回 ， 需 要 把 它 设置 成 原来 的 ClassLoader » 


更 新 Web 应 用 


zs 


bi 


RE 器 应 该 能 够 更 新 一 个 新 版 本 的 应 用 程序 ， 而 无 需 重 启 容 器 。 当 一 个 应 用 程序 更 新 时 ， 容 
应 提供 一 个 可 靠 的 方法 来 保存 该 应 用 程序 的 会 话 数据 。 


BIRR 


请 求 属性 
在 发 生 错 误 时 ，Web 应 用 程序 必须 能 够 详细 说 明 ， 应 用 程序 中 的 其 他 资源 被 用 来 提供 错误 响 
应 的 内 容 主体 。 这 些 资源 的 规定 在 部 署 描述 文件 中 配置 。 

如 果 错 误 处 理 位 于 一 个 servlet 或 JSP 页 面 : 


e 原来 打开 的 由 容器 创建 的 请 求 和 响应 对 象 被 传递 给 servlet 或 JSP 页 面 。。 

o 请 求 路 径 和 属性 被 设置 成 如 同 RequestDispatcher.forward 跳 转 到 已 经 完成 的 错误 资源 一 
样 。 

e 必须 设置 表 10-1 中 的 请 求 属性 


TABLE 10-1 Request Attributes and their types 


请 求 属性 类 型 
javax.servlet.error.status_code java.lang.Integer 
javax.servlet.error.exception_type java.lang.Class 
javax.servlet.error.message java.lang.String 
javax.servlet.error.exception java.lang.Throwable 
javax.servlet.error.request_uri java.lang.String 
javax.servlet.error.servlet_name java.lang.String 


这 些 属 性 允许 servlet 根据 状态 码 、 异 常 类 型 、 错 误 消 息 、 传 播 的 异常 对 象 、 发 生 错误 时 由 
servlet 处 理 的 请 求 URI ( 像 调 用 getRequestURI 方 法 确定 的 URI 一 样 ) 、 以 及 发 生 错误 的 
servlet 的 逻辑 名 称 来 生成 专门 的 内 容 。 


由 于 本 规范 的 2.3 版 本 引入 了 异常 对 象 属 性 列表 ， 异 常 类 型 和 错误 消息 属性 是 多 余 的 。 他 们 保 
留 向 后 兼容 早期 的 API 版 本 。 


错误 页 面 


为 了 使 开发 人 员 能 够 在 servlet 产生 一 个 错误 时 自 定 义 内 容 的 外 观 返 Web 客户 端 ， 部 署 
描述 文件 中 定义 了 一 组 错误 页 面 说 明 。 这 种 语法 允许 当 servlet 或 过 滤器 调用 响应 对 象 的 
sendError 方法 指定 状态 码 时 ， 或 如 果 servlet 产生 一 个 异常 或 错误 传播 给 容器 时 ， 由 容器 返 
回 资源 配置 。 


如 果 调 用 应 对 象 的 sendError 方法 ， 容 器 参照 为 Web 应 用 声明 的 错误 页 面 列表 ， 使 用 状态 码 
语法 并 试图 匹配 一 个 错误 页 面 。 如 果 找 到 一 个 匹配 的 错误 页 面 ， 容 器 返回 这 个 位 置 条 目 指示 
的 资源 。 


在 处 理 请 求 的 时 候 servlet 或 过 滤器 可 能 会 抛 出 以 下 异常 : 


e 运行 时 异常 或 错误 
e ServletException 或 它 的 子 类 异常 
* IOException 或 它 的 子 类 异常 


Web 应 用 程序 可 以 使 用 exception-type 元 素 声明 错误 页 面 。 在 这 种 情况 下 ， 容 器 通过 比较 抛 
出 的 异常 an exception-type 元 素 定义 的 error-page 列表 来 匹配 异常 类 型 。 在 容器 中 的 匹 
配 结果 返回 这 个 位 置 条 目 指示 的 资源 。 在 类 层次 中 最 接近 的 匹配 将 被 返回 。 


如 果 声 明 的 error-page 中 没有 包 eae type 适合 使 用 的 类 层次 结构 的 匹配 ， 那 么 抛 出 
= Benda sni ae 或 它 的 子 类 异常 ， 容 器 通过 Pons len getRootCause 方法 
提取 包装 的 异常 过 修改 错误 页 面 声明 ， 使 用 包装 的 异常 再 次 尝试 匹配 声明 的 错误 
页 面 。 


使 用 exception-type 元 素 声明 的 error-page 在 部 署 描述 文件 中 必须 唯一 的 ， 由 exception- 
type 的 类 名 决定 它 的 唯一 性 。 同 样 地 ， 使 用 status-code 元 素 声 明 的 error-page 在 部 署 描述 
文件 中 必须 是 唯一 的 ， 由 状态 码 决定 它 的 唯一 性 。 


如 果 部 署 描述 中 的 一 个 error-page 元 素 没 包含 一 个 exception-type 或 error-code 元 素 ， 错 误 
页 面 时 默认 的 错误 页 面 


rom 错误 页 面 机 制 不 会 干预 调用 使 用 RequestDispatcher 2filter.doFilter 方法 。 用 
~- ， 过 滤器 或 Servlet 有 机 会 使 用 RequestDispatcher 处 理 产 生 的 错误 。 


如 果 上 述 错误 页 面 机制 没 有 处 理 serviet 产生 的 错误 ， 那 么 容器 必须 确保 发 送 一 个 状态 500 的 
响应 o 


上 默认 的 servlet 和 容器 将 使 用 sendError 方法 ， 发 送 4xx 和 5xx 状 态 的 响应 ， 这 样 错 误 机 制 才 可 
能 会 被 调用 。 上 默认 的 servlet 和 容器 将 使 用 setStatus 方法 ， 设 置 2xx 和 3XX 的 响应 ， 并 不 会 调用 
KTA 页 页 面 机 制 。 


如 果 应 用 程序 使 用 第 2.3.3.3 节 ，" 异 步 处 理 " 中 描述 的 异步 操作 ， 那 么 处 理应 用 程序 创建 的 线程 
的 所 有 错误 是 应 用 程序 的 职责 。 容 器 应 该 通过 AsyncContext.start 方法 注意 线程 发 出 的 错误 。 
对 于 处 理 AsyncContext.dispatch 过 程 中 发 生 的 错误 ， 请 参照 相关 章节 ，“ 执 行 dispatch 方法 的 
时 候 可 能 发 生 的 错误 或 异常 必须 被 容器 按照 如 下 的 方式 捕获 并 处 理 ” 


错误 过 滤器 


错误 页 面 机 制 运 行 在 由 容器 创建 的 原来 未 包装 过 的 或 未 经 过 过 滤 的 请 求 或 响应 对 象 上 。 在 第 
6.2.5 节 “过 滤器 和 请 求 转 发 "中 描述 的 机 制 可 以 在 产生 一 个 错误 响应 之 前 用 来 指定 要 应 用 的 过 滤 


4 o 


欢迎 文件 


Web 应 用 程序 开发 人 员 可 以 在 Web 应 用 程序 部 署 描述 文件 中 定义 一 个 称 为 欢迎 文件 的 局 部 
URI 有 序列 表 。 在 Web 应 用 程序 部 署 描 述 文件 模式 中 描述 了 部 署 描述 文件 中 欢迎 文件 列表 的 
语法 。 


这 种 机 制 的 目的 是 ， 当 一 个 对 应 到 WAR 文 件 中 一 个 目录 条 目的 请 求 URI 没 有 映射 到 一 个 Web 
组 件 时 ， 允 许 部 署 者 为 容器 用 于 添加 URI 指定 局 部 URI 有 序列 表 。 这 种 请 求 被 认为 是 有 效 的 
局 部 请 求 。 


通过 下 面 常见 的 例子 来 明确 这 种 用 法 的 便利 : 可 以 定义 'index.html' 欢 迎 文件 ， 以 便 像 请 求 
URL host:port/webapp/directory/， 其 中 'directory' 是 WAR 文件 中 的 一 个 不 能 映射 到 servlet 或 
JSP 页 面 的 条 目 ， 以 下 面 的 形式 返回 给 客户 端 : ‘host:port/webapp/directory/index.html’ » 


如 果 Web 容器 接收 到 一 个 有 效 的 局 部 请 求 ，Web 容器 必须 检查 部 署 描述 文件 中 定义 的 欢迎 文 
件 列 表 。 欢 迎 文件 列表 是 一 个 没有 尾随 或 前 导 / 的 局 部 URL 有 序列 表 。Web 服务 器 必须 把 部 署 
描述 文件 中 按 指定 顺序 的 每 个 欢迎 文件 添加 到 局 部 请 求 ， 并 检查 WAR 文件 中 的 静态 资源 是 否 
映射 到 请 求 URI。 如 果 没 有 找到 匹配 的 ，Web 服务 器 必须 再 把 部 署 描述 文件 中 按 指 定 顺 序 的 
每 个 欢迎 文件 添加 到 局 部 请 求 ,并 检查 servlet 是 否 映射 到 请 求 URI。 Web 容器 必须 将 请 求 发 
Nasha nima 容器 可 使 用 转发 、 重 定向 、 或 容器 指定 的 机 制 将 请 求 发 
送 到 欢迎 资源 ， 直接 请 求 没有 什么 区 别 。 


如 果 按 上 述 的 方式 没有 找到 匹配 的 欢迎 文件 ， 容 器 可 能 会 使 用 它 认为 合适 的 方式 处 理 该 请 
求 。 对 于 有 的 配置 来 说 ， 这 可 能 意味 着 返 ae 录 列 表 ， 对 其 他 配置 来 说 可 能 返回 一 个 404 
响应 o 


考虑 一 个 Web 应 用 程序 : 
e. 部 署 描述 文件 列 出 了 以 下 的 欢迎 文件 。 


<welcome-file-list> 
<welcome-file>index.html</welcome-file> 
<welcome-file>default .jsp</welcome-file> 
</welcome-file-list> 


。 WAR 文件 中 的 静态 内 容 如 下 


/foo/index.html 
/foo/default.jsp 
/foo/orderform.html 
/foo/home.gif 
/catalog/default.jsp 
/catalog/products/shop.jsp 
/catalog/products/register.jsp 


T RURI /foo 将 被 重 定向 到 URI /foo/ ° 

T RURI /foo/ 将 返回 /foo/index.html 的 。 

请 求 URI /catalog 将 被 重 定向 到 URI /catalog/。 

请 求 URI /catalog/ 将 返回 /catalog/default.jsp。 

请 求 URI /catalog/index.html 将 导致 404 未 找到 错误 。 

请 求 URI /catalog/products 将 重 定向 到 URI /catalog/products/。 

请 求 URI /catalog/products/ 将 被 传递 给 “默认 "的 servlet (如 果 有 默认 的 servlet 的 话 ) o 
如 果 没 有 映射 到 “默认 ”的 servlet， 请 求 可 能 会 导致 一 个 404 未 找到 错误 ， 可 能 会 导致 一 个 
包括 shop.jsp 和 registerjsp 目 录 列 表 ， 或 可 能 导致 容器 定义 的 其 他 行为 。 请 参见 12.2 
节 ，“ 映 射 规范 "定义 的 “默认 ”servlet 。 

所 有 上 述 的 静态 内 容 都 可 以 打包 到 JAR 文件 的 META-INF/resources 目 录 中 。 这 个 JAR 
文件 可 以 放 到 Web 应 用 的 WEB-INF/lib 目录 下 。 


Web 环境 


oe Be 


servlet 容器 不 属于 Java EE 技术 标准 的 实现 ， 鼓 励 实现 这 个 容器 但 不 是 必需 的 ， 实 现 应 用 环 
境 的 功能 请 参见 第 15.2.2 节 中 描述 的 “Web 应 用 环境 "和 Java EE 规范 。 如 果 他 们 没有 实现 需要 
支持 这 种 环境 的 条 件 ， 根 据 部 署 依赖 它们 的 应 用 程序 ， 容 器 应 该 提供 一 个 警告 。 


Web 应 用 部 署 


当 一 个 Web 应 用 程序 部 署 到 容器 中 ， 在 Web 应 用 程序 开始 处 理 客户 端 请 求 之 前 ， 必 须 按照 
下 述 步 又 顺序 执行 。 


e. 实例 化 部 署 描述 文件 中 <listener> 元 素 标 识 的 每 个 事件 监听 器 的 一 个 实例 。 

e 对 于 已 实例 化 的 实现 了 ServletContextListener 接口 的 监听 器 实例 ， 调 用 
contextlnitialized() 方法 。 

© 实例 化 部 署 描述 文件 中 <filter> 元 素 标 识 的 每 个 过 滤器 的 一 个 实例 ， 并 调用 每 个 过 滤器 

实例 的 init() 方 法 。 

包含 <load-on-startup> 元 素 的 <servlet> 元 素 ， 根 据 load-on-startup 元 素 值 定 义 的 顺序 

为 每 个 servlet 实例 化 一 个 实例 ， 并 调用 每 个 servlet 实例 的 init() 方法 。 


包 念 web.xml 部 署 描述 符 


如 果 Web 应 用 不 包含 任何 servlet、 过 滤器 、 或 监听 器 组 件 或 使 用 注解 声明 相同 的 ， 那 么 可 以 
不 需要 web.xml 文件 。 换 名 话说 ， 只 包含 静态 文件 或 JSP 页 面 的 应 用 程序 并 不 需要 一 个 
web.xml 的 存在 。 


应 用 的 事件 机 制 给 Web 应 用 开发 人 员 更 好 地 控制 ServletContext ` HttpSession 和 
ServietRequest 的 生命 周期 ， 可 以 更 好 地 代码 分 解 ， 并 在 管理 Web 应 用 使 用 的 资源 上 提高 了 


应 用 事件 监听 器 是 实现 一 个 或 多 个 Servlet 事件 监听 器 接口 的 类 。 它 们 是 在 部 署 Web 应 用 
时 ， 实 例 化 并 注册 到 Web 容器 中 。 它 们 由 开发 人 员 在 WAR 包 中 提供 。 


Servlet 事件 监听 器 支持 在 ServletContext、HttpSession 和 ServletRequest 状态 改变 时 进行 
事件 通知 。Servlet 上 下 文 监听 器 是 用 来 管理 应 用 的 资源 或 JVM 级 别 持 有 的 状态 。HTTP 会 话 
监听 器 是 用 来 管理 从 相同 客户 端 或 用 户 进 入 Web 应 用 的 一 系列 请 求 关 联 的 状态 或 资源 。 
Servlet 请 求 监听 器 是 用 来 管理 整个 Servlet 请 求生 命 周期 的 状态 。 异 步 监 听 器 是 用 来 管理 异 
步 事 件 ， 例 1 如 超时 和 完成 异步 处 理 o 

可 以 有 多 个 监听 器 类 监听 每 一 个 事件 类 型 ， 且 开发 人 员 可 以 为 每 一 个 事件 类 型 指定 容器 调用 
监听 器 bean 的 顺序 。 


事件 类 型 和 监听 器 接口 
事件 类 型 和 监听 器 接口 用 于 监控 下 表 所 示 的 | 


TABLE 11-1 Servlet Context Events 


事 

ce 监听 器 接口 

型 

_ Servlet 上 下 文 刚刚 创建 并 可 用 于 

sl 服务 它 的 第 一 个 请 求 ， 或 者 javax.servlet.ServletContextListener 

期 Servlet 上 下 文 即将 关闭 

属 

X 的 属性 已 添 

‘ aa E javax.servlet.ServletContextAttributeListener 
余 、 或 车 

改 


TABLE 11-2 HTTP Session Events 


事件 
生命 
周期 
属性 
更 改 
改变 
1D 

会 话 
迁移 
对 象 


绑 定 


AL 
BE 


Dik CALE MARR 。 


已 经 在 HttpSession 上 添加 、 
移 除 、 或 替换 属性 


HttpSession 的 ID 将 被 改变 


HttpSession 已 被 激活 或 印 
化 


对 象 已 经 从 HttpSession 绑 定 
或 解除 绑 定 


TABLE 11-3 Servlet Request Events 


描述 


E 


一 个 servlet 请 求 已 经 开始 由 
Web 组 件 处 理 


已 经 在 ServletRequest 上 添 
加 、 移 除 、 或 替换 属性 。 


超时 、 连 接 终止 或 完成 异步 处 


理 


监听 器 使 用 的 一 个 例子 


为 了 说 明 事 件 使 用 方案 ， 考 虑 一 个 包含 一 些 使 用 数据 库 的 Servlet 的 简单 Web 应 用 。 开 发 人 
员 提 供 了 一 个 Servlet 上 下 文 监听 器 类 用 于 管理 数据 库 连 接 。 


监听 器 接口 


javax.servlet.http.HttpSessionListener 


javax.servlet.http.HttpSessionAttributeListener 


javax.servlet.http.HttpSessionldListener 


javax.servlet.http.HttpSessionActivationListener 


javax.servlet.http.HttpSessionBindingListener 


监听 器 接口 


javax.serviet.ServietRequestListener 


javax.serviet.ServietRequestAttributeListener 


javax.serviet.AsyncListener 


1， 当 应 用 启动 时 ， 监 听 器 类 得 到 通知 。 应 用 登录 到 数据 库 ， 并 在 servlet 上 下 文中 存储 连 


接 。 


2. 应 用 中 的 Serviet 根据 需要 ， 在 Web 应 用 的 活动 期 间 访 问 连 接 。 


a 


3. 2 Web 服务 器 关闭 时 ， 或 应 用 从 Web 服务 器 移 除 时 ， 监 听 器 类 得 到 通知 且 关闭 数据 库 
连接 。 


监听 器 类 的 配置 


提供 监听 器 类 


Web 应 用 的 开发 人 员 提 供 实 现 了 一 个 或 多 个 在 javax.servlet API 中 的 监听 器 接口 的 监听 器 
类 。 每 一 个 监听 器 类 必须 有 一 个 无 参 构造 器 。 监 听 器 类 打包 到 WAR 包 中 ， 或 者 在 WEB- 
INF/classes 归档 项 下 ， 或 者 在 WEB-INF/lib 目录 的 一 个 JAR 内 部 。 


部 着 声明 


监听 器 类 在 Web 应 用 部 署 描述 符 中 使 用 listener 元 素 声 明 。 它 们 根据 类 名 列 出 的 顺序 就 是 它 
们 被 调用 的 顺序 。 与 其 他 监听 器 不 同 ，AsyncListener 类 型 的 监听 器 可 能 仅 通过 编程 式 注 册 
(使 用 一 个 ServletRequest) ° 


TASTE 


Web 容器 创建 每 一 个 监听 器 类 的 一 个 实例 ， 并 在 应 用 处 理 第 一 个 请 求 之 前 为 事件 通知 注册 
它 。Web 容 器 根据 他 们 实现 的 接口 注册 监听 器 实例 ， 且 按照 它们 出 现在 部 署 描述 符 中 的 顺 
序 。 在 Web 应 用 执行 期 间 ， 监 听 器 按照 它们 注册 的 顺序 被 调用 ， 但 也 有 例外 ， 例 如 ， 
HttpSessionListener.destroy 按照 相反 的 顺序 调用 。 参 考 8.2.3 节 “装配 web.xml、web- 
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fragment.xml 描述 符 和 注解 ”。 


关闭 时 通知 


在 应 用 关闭 时 ， 监 听 器 以 它们 声明 时 相反 的 顺序 得 到 通知 ， 且 通知 会 话 监 听 器 在 通知 上 下 文 
监听 器 之 前 。 通 知 会 话 监 听 器 session 失效 必须 在 通知 上 下 文 监听 器 关闭 之 前 。 


部 署 描述 符 示 例 


以 下 示例 是 注册 两 个 Servlet 上 下 文生 命 周 期 监听 器 和 一 个 HttpSession 监听 器 的 部 署 语法 。 
假设 com.acme.MyConnectionManager 和 com.acme.MyLoggingModule 两 个 都 实现 了 
javax.servlet.ServletContextListener ， 且 com.acme.MyLoggingModule 又 实现 了 
javax.servlet.http.HttpSessionListener ° #67h > FRA RAZ 
com.acme.MyConnectionManager 在 com.acme.MyLoggingModule 得 到 Servlet 上 下 文生 
周期 事件 的 通知 。 下 面 是 这 个 应 用 的 部 署 描述 符 : 


命 


<web -app> 
<display-name>MyListeningApplication</display-name> 
<listener> 
<listener-class>com.acme.MyConnectionManager</listenerclass> 
</listener> 
<listener> 
<listener-class>com.acme.MyLoggingModule</listener-class> 
</listener> 
<servlet> 
<display-name>RegistrationServlet</display -name> 
..etc 
</servlet> 
</web -app> 


Te OT a SE i He ATE 


Ge 38 ae 


容器 需要 在 开始 执行 进入 应 用 的 第 一 个 请 求 之 前 完成 Web 应 用 中 的 监听 器 类 的 实例 化 。 容 器 
必须 保持 到 每 一 个 监听 器 的 引用 直到 为 Web 应 用 最 后 一 个 请 求 提供 服务 
能 会 同时 发 生 。 不 要 求 容器 同步 到 属性 监听 


ABA 


ServletContext 和 HttpSession 对 象 的 属性 改变 可 
器 类 产生 的 通知 。 维 护 状态 的 监听 器 类 负责 数据 的 完整 性 且 应 明确 处 理 这 种 情况 。 


监听 器 异常 


一 个 监听 器 里 面 的 应 用 代码 在 运行 期 间 可 能 会 抛 出 异常 。 一 些 监听 器 通知 发 生 在 应 用 中 的 另 

一 个 组 件 调用 树 过 程 中 。 这 方面 的 一 个 例子 是 一 个 Servlet 设置 了 会 话 属性 ， 该 会 话 监听 器 抛 
出 未 处 理 异 常 。 容 器 器 必须 允许 未 处 理 的 异常 由 描述 在 10.9 节 “错误 处 理 " 的 错误 页 面 机 制 处 理 。 
如 果 没 有 为 这 些 异 常 指定 错误 页 面 ， 容 器 必须 确保 返回 一 个 状态 码 为 500 的 响应 。 这 种 情况 

下 ， 不 再 有 监听 器 根据 事件 被 调用 。 


有 些 异 常 不 会 发 生 在 应 用 中 的 另 一 个 组 件 调 用 栈 过 程 中 。 这 方面 的 一 个 例子 SessionListener 
接收 通知 的 会 话 已 经 超时 并 抛 出 未 处 理 的 异常 ， 或 者 ServletContextListener 在 Servlet 上 下 
文 初 始 化 通知 期 间 抛 出 未 处 理 异 常 ， 或 者 ServietRequestListener 在 初始 化 或 销毁 请 求 对 象 
的 通知 期 间 抛 出 未 处 理 异 常 。 这 种 情况 下 ， 开 发 人 员 没 有 机 会 处 理 这 种 异常 。 容 器 可 以 以 
HTTP 状态 码 500 来 响应 所 有 后 续 的 到 Web 应 用 的 请 求 ， 表 示 应 用 出 错 了 。 


开发 人 员 和 希望 发 生 在 监听 器 产生 一 个 异常 且 在 通知 方法 里 面 必 须 处 理 它们 自己 的 异常 之 后 的 
正常 处 理 。 


分 布 式 容器 


在 分 布 式 Web 容器 中 ，HttpSession 实例 被 限 到 特定 的 IVM 服务 会 话 请 求 ， 且 
ServletContext 对 象 被 限定 到 Web 容器 所 在 的 JVM。 分 布 式 容器 不 需要 传播 Servlet 上 下 文 
事件 或 HttpSession 事件 到 其 他 JYVM。 监 听 器 类 实例 被 限定 到 每 个 JVM 的 每 个 部 署 描述 符 声 
明 一 个 。 


会 话 事 件 


监听 器 类 提供 给 开发 人 员 一 种 跟踪 Web 应 用 内 会 话 的 方式 。 它 通常 是 有 用 的 ， 在 跟踪 会 话 知 
道 一 个 会 话 是 否 变 为 失效 ， 因 为 容器 超时 会 话 ， 或 因为 应 用 内 的 一 个 Web 组 件 调用 了 
invalidate 方法 。 该 区 别 可 能 会 间接 地 决定 使 用 监听 器 和 HttpSession API 方 法 。 


映射 请 求 到 Servlet 


Web 容器 需要 本 章 描 述 的 映射 技术 去 映射 客户 端 请 求 到 Servlet (该 规范 2.5 以 前 的 版 本 ， 使 
用 这 些 映射 技术 是 作为 一 个 建议 而 不 是 要 求 ， 允 许 servlet 容器 各 有 其 不 同 的 策略 用 于 映射 客 
Pišta 


请 求 到 servlet) 。 


使 用 URL 路 径 


在 收 到 客户 端 请 求 时 ，web 容器 确定 转发 到 哪 一 个 Web 应 用 。 选 择 的 Web 应 用 必须 具有 最 
长 的 上 下 文 路 径 匹 配 请 求 URL 的 开始 。 当 映射 到 Servlet 时 ，URL 匹配 的 一 部 分 是 上 下 文 。 


Web 容器 接 下 来 必须 用 下 面 描述 的 路 径 匹 配 步骤 找 出 Servlet 来 处 理 请 求 。 用 于 映射 到 
Servlet 的 路 径 是 请 求 对 象 的 请 求 URL 减 去 上 下 文 和 路 径 参 数 部 分 。 下 面 的 URL 路 径 映 射 规 
则 按 顺 序 使 用 。 使 用 第 一 个 匹配 成 功 的 且 不 会 进一步 尝试 匹配 : 


1. 
2. 


容器 将 尝试 找到 一 个 请 求 路 径 到 servlet 路 径 的 精确 匹配 。 成 功 匹 配 则 选择 该 servlet。 
人 试 匹 配 最 长 路 径 前 级 。 这 是 通过 一 次 一 个 目录 的 遍历 路 径 树 完成 的 ， 使 
ATF ee 最 长 匹配 确定 选择 的 Servlet 。 


如 果 URL 最 后 一 部 分 包含 一 个 扩展 名 (如 jsp) ，servlet 容 器 将 视图 匹配 为 扩展 名 处 理 请 
求 的 Servlet 。 De naje 一 部 分 的 最 后 一 个 "字符 之 后 。 

如 果 前 三 个 规则 都 没有 产生 一 个 servlet 匹 配 ， 容 器 将 试图 为 请 求 资源 提供 相关 的 内 容 。 
如 果 应 用 中 定义 了 一 个 “default*servlet， 它 将 被 使 用 。 许 多 容器 提供 了 一 种 隐 式 的 default 
servlet 用 于 提供 内 容 。 容器 必须 使 用 区 分 大 小 写字 符 串 比较 匹配 。 


映射 规范 


在 web 应 用 部 署 描述 符 中 ， 以 下 语法 用 于 定义 映射 : 


e. 以 /字符 开始 、 以 '/*' 后 缀 结尾 的 字符 囊 用 于 路 径 匹 配 。 

e 以 “开始 的 字符 串 用 于 扩展 名 映射 。 

。 空 字符 串 ”" 是 一 个 特殊 的 URL 模 式 ， 其 精确 映射 到 应 用 的 上 下 文 根 ， 即 ，http:Whost:portW/ 
请 求 形式 。 在 这 种 情况 下 ， 路 径 信息 是 " 且 servlet 路 径 和 上 下 文 路 径 是 空 字符 串 〈”) 。 

. 只 包含 oj/ 字符 的 字符 串 表 示 应 用 的 “default*servlet。 在 这 种 情况 下 ，servlet 路 径 是 请 求 
URL 减 去 上 下 文 路 径 且 路 径 信 息 是 null 。 

e 所 有 其 他 字符 串 仅 用 于 精确 匹配 。 


如 果 一 个 有 效 的 web.xml (在 从 fragment 和 注解 合并 了 信息 后 ) 中 有 任意 一 个 url-pattern > 
其 映射 到 多 个 servlet， 那 么 部 署 将 失败 。 
隐 式 映射 


如 果 容 器 有 一 个 内 部 的 JSP 容 器 ，.jsp 扩 展 名 映射 到 它 ， 人 允许 执行 JSP 页 面 的 要 求 。 该 映射 被 
称 为 隐 式 映射 。 如 果 Web 应 用 定义 了 一 个 jsp 映射， 它 的 优先 级 高 于 隐 式 映射 。 


Servlet 容器 允许 进行 其 他 的 隐 式 映射 ， 只 要 显示 映射 的 优先 。 例 如 ， 一 个 *.shtml 隐 式 映射 
可 以 映射 到 包含 在 服务 器 上 的 功能 。 

示例 映射 集合 

请 看 下 面 的 一 组 映射 : 


TABLE 12-1 Example Set of Maps 


路 径 模 式 Servlet 
/foo/bar/* servlet 
/baz/* servlet2 
/catalog servlet3 
* bop servlet4 


将 产生 以 下 行为 : 


TABLE 12-2 Incoming Paths Applied to Example Maps 


访问 的 路 径 Servlet 处 理 请 求 


/foo/bar/index.html servlet 
/foo/bar/index.bop servlet 
/baz servlet2 
/baz/index.html servlet2 
/catalog servlet3 
/catalog/index.html “default” servlet 
/catalog/racecar.bop servlet4 
lindex.bop servlet4 


请 注意 ， 在 Icatalog/index.html 和 /catalog/racecar.bop 的 情况 下 ， 不 使 用 映射 到 %catalog "的 
servlet， 因 为 不 是 精确 匹配 的 。 


安全 


应 用 开发 人 员 创 建 Web 应 用 ， 他 给 、 销 售 或 其 他 方式 转 入 应 用 给 部 署 人 员 ， 部 署 人 员 和 履 盖 安 
装 到 运行 时 环境 。 应 用 开发 人 员 与 部 署 人 员 沟 通 部 署 系统 的 安全 需求 。 该 信息 可 以 通过 应 用 
部 署 描述 符 声 明 传 达 ， 通 过 在 应 用 代码 中 使 用 注解 ， 或 通过 ServletRegistration 接口 的 
setServletSecurity 方法 编程 。 


本 节 描 述 了 Servlet 容器 安全 机 制 、 接 口 、 部 署 描述 符 和 基于 注解 机 制 和 编程 机 制 用 于 传达 应 
用 安全 需求 。 


n 
web 应 用 包含 的 资源 可 以 被 多 个 用 户 访 问 。 这 些 资 源 常 常 不 受 保护 的 遍历 ， 开 放 网 络 如 
Internet。 在 这 样 的 环境 ， 大 量 的 web 应 daje 机 ° o g laik nos 可 能 会 
有 所 不 同 ， 但 servlet 容器 有 满足 这 些 需求 的 机 制 和 ， 共 用 如 下 一 些 特性 


© 身份 认证 : 表示 通信 实体 彼此 证 明 他 们 具体 身份 的 行为 是 被 授权 访问 的 。 

e 资源 访问 控制 : 表示 和 资源 的 交互 是 受 限于 集合 的 用 户 或 为 了 强制 完整 性 、 保 密 性 、 或 
可 用 性 约束 的 程序 。 

© 数据 完整 性 : 表示 用 来 证 明 信 息 在 传输 过 程 中 没有 被 第 三 方 修改 。 

o 保密 或 数据 隐私 : 表示 用 来 保证 信息 只 对 以 授权 访问 的 用 户 可 用 。 


声明 式 安全 


声明 式 安全 是 指 以 在 应 用 外 部 的 形式 表达 应 用 的 安全 模型 需求 ， 包 括 角色 、 访 问 控制 和 认证 
需求 。 部 署 描述 符 是 web 应 用 中 的 声明 式 安全 的 主要 手段 。 
部 署 人 员 映 射 应 用 的 逻辑 安全 需求 到 特定 于 运行 时 环境 的 安全 策略 的 表示 。 在 运行 时 ， 


serviet 容器 使 用 安全 策略 表示 来 实施 认证 和 授权 。 


安全 模型 适用 于 web 应 用 的 静态 内 容 部 分 和 客户 端 请 求 到 的 应 用 内 的 servlet 和 过 滤器 。 安 全 
模型 不 适用 于 当 servlet 使 用 RequestDispatcher 调用 静态 内 容 或 使 用 forward 或 include 到 
的 servlet ° 


编程 式 安 全 
当 仅 仅 声 明 式 安全 是 不 足以 表达 应 用 的 安全 模型 时 ， 编 程式 安全 被 用 于 意识 到 安全 的 应 用 。 


编程 式 安全 包括 以 下 HttpServletRequest 接口 的 方法 : 


e authenticate 

e login 

e logout 

e getRemoteUser 
e isUserlnRole 

e getUserPrincipal 


login 方法 允许 应 用 执行 用 户 名 和 密码 收集 (作为 一 种 Form-Based Login 的 替代 ) 。 
authenticate 方法 允许 应 用 由 容器 发 起 在 一 个 不 受 约束 的 请 求 上 下 文 内 的 来 访 者 请 求 认 证 。 
logout 方法 提供 用 于 应 用 重 置 来 访 者 的 请 求 身份 。 

getRemoteUser 方法 由 容器 返回 与 该 请 求 相关 的 远程 用 户 〈 即 来 访 者 ) 的 名 字 。 
isUserlnRole 方法 确定 是 否 与 该 请 求 相关 的 远程 用 户 (PKK) 在 一 个 特定 的 安全 角色 
中 。 


getUserPrincipal 方法 确定 远程 用 户 〈 即 来 访 者 ) 的 Principal 名 称 并 返回 一 个 与 远程 用 户 相 
java.security. Principal xt R > M getUserPrincipal 返回 的 Principal 的 getName 方法 返 
远程 用 户 的 名 字 。 这 些 API 允许 Servlet 基于 获得 的 信息 做 一 些 业务 逻辑 决策 。 


如 果 没 有 用 户 通过 身份 认证 ，getRemoteUser 方法 返回 null > isUserlnRole 方法 总 返 
false，getUserPrincipal 方法 总 返回 null 。 


isUserlnRolem 方法 需要 一 个 引用 应 用 角色 的 参数 。 对 于 用 在 调用 isUserlnRole 的 每 一 个 单独 
的 角色 引用 ， 一 个 带 有 关联 到 角色 引用 的 role-name 的 security-role-ref 元 素 应 该 声明 在 部 署 

描述 符 中 。 每 一 个 security-role-ref 元 素 应 该 包含 一 个 role-link FA > AERE MM AR g A 

色 引 用 链接 到 的 应 用 安全 角色 名 称 。 容 器 使 用 sni -role-ref 的 role-name 是 否 等 于 角色 引 

用 来 决定 哪 一 个 security-role 用 于 测试 用 户 是 否 在 身份 中 。 


例如 ， 映 射 安全 角色 应 用 “FOO” 到 role-name 为 "manager" 的 安全 角色 的 语法 是 | 


<security-role-ref> 
<role-name>F00</role-name> 
<role-link>manager</role-link> 

</security-role-ref> 


在 这 种 情况 下 ， 如 果 属 于 “manager 安 全 角色 的 用 户 调 用 了 servlet， 则 调用 
isUserlnRole("FOO") API 的 结果 是 true。 


如 果 用 于 调用 isUserlnRole 的 一 个 角色 引用 ， 没 有 匹配 的 security-role-ref 存在 ， 容 器 必须 
默认 以 security-role 的 role-name 等 于 用 于 调用 的 角色 引用 来 测试 用 户 身份 。 


角色 名 * 应 该 从 不 用 作 调 用 isUserlnRole 的 参数 。 任 何以 * 调用 isUserlnRole 必须 返回 
false。 如 果 security-role 的 role-name 使 用 ** 测试 ， 且 应 用 没有 声明 一 个 role-name 
为 ** 的 应 用 security-role > isUserlnRole 必须 仅 返 回 true ° 


如 果 用 户 已 经 认证 ; 即 ， 仅 当 getRemoteUser 和 getUserPrincipal 将 同时 返回 非 null ti ° € 
则 ， 容 器 必须 检查 用 户 身 份 是 否 在 应 用 角色 中 。 


security-role-ref 元 素 声 明 通 知 部 署 人 员 应 用 使 用 的 角色 引用 和 必须 定义 哪 一 个 映射 


> > e KE 
编程 式 安 全 策略 配置 
本 章 定 义 的 注解 和 API 提 供用 于 配置 Servlet 容器 强制 的 安全 约束 。 


@ServletSecurity 注解 


@ServletSecurity 提供 了 用 于 定义 访问 控制 约束 的 另 一 种 机 制 ， 相 当 于 那些 通过 在 便携 式 部 
署 描述 符 中 声明 式 或 通过 ServletRegistration 接口 的 setServletSecurity 方法 编程 式 表示 。 
Servlet 容器 必须 支持 在 实现 javax.servlet.Servlet 接口 的 类 (和 它 的 子 类 ) 上 使 用 
@ServletSecurity 注解 。 


package javax.servlet.annotation; 


@Inherited 
@Documented 
@Target(value=TYPE) 
QRetention(value=RUNTIME) 
public @interface ServletSecurity { 
HttpConstraint value(); 
HttpMethodConstraint[] httpMethodConstraints(); 


TABLE 13-1 The ServletSecurity Interface 


元 素 we ik 默认 
HttpConstraint 定义 了 应 用 到 没有 在 
value httpMethodConstraints 返回 的 数组 中 表 @HittpConstraint 
示 的 所 有 HTTP 方 法 的 保护 。 
httpMethodConstraints HTTP 方法 的 特定 限制 数组 {} 
@HttpConstraint 


@HttpConstraint 注解 用 在 @ServletSecurity 中 表示 应 用 到 所 有 HTTP 协议 方法 的 安全 的 
束 ， 且 HTTP 协议 方法 对 应 的 @HttpMethodConstraint 没有 出 现在 @ServletSecurity 注解 
中 。 


对 于 一 个 @HttpConstraint 返回 所 有 默认 值 发 生 在 与 至 少 一 个 @HttpMethodConstraint 返回 
不 同 于 所 有 默认 值 的 组 合 的 特殊 情况 ，@HttpMethodConstraint 表示 没有 安全 约束 被 应 用 到 
任何 HTTP 协议 方法 ， 否 则 一 个 安全 约束 将 应 用 。 这 个 例外 是 确保 这 些 潜在 的 非特 定 
@HttpConstraint 使 用 没有 产生 约束 ， 这 将 明确 建立 不 受 保护 的 访问 这 些 方法 ; 因为 ， 它 们 没 
AR RK > 


package javax.servlet.annotation; 


@Documented 

@Retention(value=RUNTIME ) 

public @interface HttpConstraint { 
ServletSecurity.EmptyRoleSemantic value(); 
java.lang.String[] rolesAllowed(); 
ServletSecurity.TransportGuarantee transportGuarantee(); 


} 
元 素 a ik 默认 
出 — ve Žž} Os R 5 IERT 
eo S rolesAllowed:& ™ 个 空 数组 ， (只 ) 应 用 的 默认 PERMIT 
授权 语义 。 
rolesAllowed 包含 授权 角色 的 数组 {} 
transportGuarantee ”在 连接 的 请 求 到 达 时 必须 满足 的 数据 保护 需求 。 NONE 


@HttpMethodConstraint 


@HttpMethodConstraint 注解 用 在 @ServietSecurity 注解 中 表示 在 特定 HTTP 协议 消息 上 的 
安全 约束 。 


package javax.servlet.annotation; 


@Documented 

QRetention(value=RUNTIME) 

public @interface HttpMethodConstraint { 
ServletSecurity.EmptyRoleSemantic value(); 
java.lang.String[] rolesAllowed(); 
ServletSecurity.TransportGuarantee transportGuarantee(); 


TABLE 13-3 The HttpMethodConstraint Interface 


元 素 描述 默认 
value HTTP 协 议 方 法 名 
当 wa 一 个 空 > 2 g 只 S A er ~ 
Ral ene 当 rolesAllowed 返 回 一 个 空 数组 ， (R) 应 用 的 默认 PERMIT 


授权 语义 。 
rolesAllowed 包含 授权 角色 的 数组 {} 


transportGuarantee 在 连接 的 请 求 到 达 时 必须 满足 的 数据 保护 需求 。 NONE 


@ServletSecurity 注解 可 以 指定 在 (更 准确 地 说 ， 目 标 是 ) Servlet 实现 类 上 ， 且 根据 
@Inherited 元 注解 定义 的 规则 ， 它 的 值 是 被 子 类 继承 的 。 至 多 只 有 一 个 @ServletSecurity 注 
解 实例 可 以 出 现在 Servlet 实现 类 上 ， 且 @ServletSecurity 注解 必须 不 指定 在 (更 准确 地 说 ， 
目标 是 ) Java 方法 上 。 


当 一 个 或 多 个 @HttpMethodConstraint 注解 定义 在 @ServletSecurity 注 解 中 时 ， 每 一 个 
@HttpMethodConstraint 定义 的 security-constraint， 其 应 用 到 @HttpMethodConstraint 中 标 
识 的 HTTP 协议 方法 。 除 了 它 的 @HttpConstraint 返回 所 有 默认 值 、 和 它 包 含 至 少 一 个 返回 
不 同 于 所 有 默认 值 的 @HttpMethodConstraint 的 情况 之 外 ，@ServletSecurity 注解 定义 另 一 
个 security-constraint 应 该 到 所 有 还 没有 定义 相关 @HttpMethodConstraint 的 HTTP 协议 方 
法 。 


定义 在 便携 式 部 署 描述 符 中 的 security-constraint 元 素 用 于 对 所 有 出 现在 该 约束 中 的 url- 
pattern 授权 。 


当 在 便携 式 部 署 描述 符 中 的 一 个 security-constraint 包含 一 个 url-pattern， 其 精确 匹配 一 个 使 
用 @ServletSecurity 注 解 的 模式 映射 到 的 类 ， 该 注解 必须 在 由 容器 在 该 模式 上 强制 实施 的 约束 
上 没有 效果 。 


当 为 便携 式 部 署 描述 符 定义 了 metadata-complete=true 时 ，@ServletSecurity 注解 不 会 应 用 
到 部 署 描 述 符 中 的 任何 url-pattern 映射 到 (任何 servlet 映 射 到 ) 的 注解 类 。 


@ServletSecurity 注解 不 应 用 到 ServletRegistration 使 用 ServletContext 接口 的 
addServlet(String, Servlet) 方法 创建 的 url-pattern， 除 非 该 Servlet 是 由 ServletContext 接口 
的 createServlet 方法 构建 的 。 除 了 上 面 列 出 的 ， 当 一 个 Servlet 类 注解 了 
@ServletSecurity， 该 注解 定义 的 安全 约束 应 用 到 所 有 url-pattern 映射 到 的 所 有 Servlet 映射 
到 的 类 。 


当 一 个 类 没有 加 @ServletSecurity 注解 时 ， 应 用 到 从 那个 类 映射 到 的 Servlet 的 访问 策略 是 由 
合适 的 security-constraint 元 素 确定 的 ， 如 果 有 ， 在 相关 的 便携式 部 署 描述 符 ， 或 者 由 约束 禁 
止 任 何 这 样 的 标签 ， 则 如 果 有 ， 为 目标 servlet 通过 ServletRegistration 接口 的 
setServletSecurity 方法 编程 式 确 定 的 。 


示例 
以 下 示例 演示 了 ServletSecurity 注解 的 使 用 。 
CODE EXAMPLE 13-1 for all HTTP methods, no constraints 


@ServletSecurity 
public class Example1 extends HttpServlet { 


} 


CODE EXAMPLE 13-2 for all HTTP methods, no auth-constraint, confidential transport 
required 


@ServletSecurity(@HttpConstraint(transportGuarantee = 
TransportGuarantee.CONFIDENTIAL ) ) 

public class Example2 extends HttpServlet { 

} 


CODE EXAMPLE 13-3 for all HTTP methods, all access denied 


@ServletSecurity(@HttpConstraint(EmptyRoleSemantic. DENY) ) 
public class Example3 extends HttpServlet { 
} 


CODE EXAMPLE 13-4 for all HTTP methods, auth-constraint requiring membership in 
Role R1 


@ServletSecurity(@HttpConstraint(rolesAllowed = "R1")) 
public class Example4 extends HttpServlet { 
} 


CODE EXAMPLE 13-5 for All HTTP methods except GET and POST, no constraints; 
forethods GET and POST, auth-constraint requiring membership in Role R1; for POST, 
confidential transport required 


@ServletSecurity((httpMethodConstraints = { 
@HttpMethodConstraint(value = "GET", rolesAllowed = "R1"), 
@HttpMethodConstraint(value = "POST", rolesAllowed = "R1", 
transportGuarantee = TransportGuarantee.CONFIDENTIAL) 


1) 
public class Example5 extends HttpServlet 1 


} 


CODE EXAMPLE 13-6 for all HTTP methods except GET auth-constraint requiring 
membership in Role R1; for GET, no constraints 


@ServletSecurity(value = @HttpConstraint(rolesAllowed = "R1"), 
httpMethodConstraints = @HttpMethodConstraint("GET")) 

public class Example6 extends HttpServlet { 

} 


CODE EXAMPLE 13-7 for all HTTP methods except TRACE, auth-constraint requiring 
membership in Role R1; for TRACE, all access denied 


@ServletSecurity(value = @HttpConstraint(rolesAllowed = "R1"), 
httpMethodConstraints = @HttpMethodConstraint(value="TRACE", 
emptyRoleSemantic = EmptyRoleSemantic.DENY) ) 

public class Example7 extends HttpServlet { 

} 


映射 @ServletSecurity 为 security-constraint 


本 节 将 介绍 @ServletSecurity 注解 映射 为 它 等 价 表 示 ，security-constraint 元 素 。 这 提供 了 使 
用 已 存在 容器 的 security-constraint 实施 机 制 来 简化 实施 。 由 Servlet 容器 实施 的 
@ServletSecurity 注解 必须 在 实施 的 效果 上 是 等 价 的 ， 由 容器 从 在 本 节 中 定义 的 映射 产生 
security-constraint 元 素 。 


@ServletSecurity 注解 用 于 定义 一 个 方法 无 关 的 @HttpConstraint， 且 紧 跟着 一 个 包含 零 个 或 
多 个 @HttpMethodConstraint 规格 的 列表 。 方 法 无 关 的 约束 应 用 到 那些 没有 定义 HTTP 特定 
方法 约束 的 所 有 HTTP 方法 。 当 没有 包含 @HttpMethodConstraint 1% > @ServietSecurity 
注解 相当 于 包含 一 个 web-resource-collection 的 单个 security-constraint 元 素 ， 且 web- 
resource-collection 不 包含 http-method 元 素 ， 因 此 涉及 到 所 有 HTTP 方法 。 


下 面 的 例子 展示 了 把 一 个 不 包含 @HttpMethodConstraint 注解 的 @ServletSecurity 注解 表示 
为 单个 security-constraint 元 素 。 相 关 的 servlet (registration) 定义 的 url-pattern 元 素 将 被 包 
含 在 web-resource-collection 中 ， 任 何 包 含 的 auth-constraint 和 user-data-constraint 元 素 的 
存在 和 值 ， 将 由 定义 在 13.4.1.3 节 的 “映射 @HttpConstraint 和 @HttpMethodConstraint 为 
XML” 的 映射 的 @HttpConstraint 的 值 确定 。 


CODE EXAMPLE 13-8 mapping @ServletSecurity with no contained 
@HttpMethodConstraint 


@ServletSecurity(@HttpConstraint(rolesAllowed = "Rolei") ) 


<security-constraint> 
<web-resource-collection> 
<url-pattern>...</url-pattern> 
</web-resource-collection> 
<auth-constraint> 
<role-name>Role1</role-name> 
</auth-constraint> 
</security-constraint> 


当 指 定 了 一 个 或 多 个 @HttpMethodConstraint 元 素 ， 方 法 无 关 的 约束 关联 一 个 单个 security- 
constraint 71% > # > web-resource-collection 包含 了 为 每 一 个 HTTP 方法 命名 在 
@HttpMethodConstraint 元 素 中 的 http-method-omission 元 素 。 如 果 方 法 无 关 的 约束 返回 所 
有 默认 值 和 至 少 一 个 @HttpMethodConstraint 不 是 ， 包 含 http-method-omission 元 素 的 


security-constraint 必须 不 被 创建 。 每 一 个 @HttpMethodConstraint 与 另 一 种 包含 一 个 web- 
resource-collection 的 security-constraint 关联 ，web-resource-collection 包含 一 个 使 用 相应 
HTTP 方法 命名 的 http-method 元 素 。 


下 面 的 例子 展示 了 映射 带 有 单个 @HttpMethodConstraint 的 @ServletSecurity 注解 为 两 种 
security-constraint 元 素 。 相 应 的 Servlet (registration) 定义 的 url-pattern 元 素 将 被 包含 在 两 
种 约束 的 web-resource-collection 中 ， 且 任何 包含 的 auth-constraint 和 user-data-constraint 
元 素 的 存在 和 值 ， 将 由 定义 在 13.4.1.3 节 的 “映射 @HttpConstraint 和 @HttpMethodConstraint 
为 XML” 的 映射 关联 的 @HttpConstraint 和 @HttpMethodConstraint 的 值 确定 。 


CODE EXAMPLE 13-9 mapping @ServletSecurity with contained @HttpMethodConstraint 


@ServletSecurity(value=@HttpConstraint(rolesAllowed = "Rolei"), 
httpMethodConstraints = @HttpMethodConstraint(value = "TRACE", 
emptyRoleSemantic = EmptyRoleSemantic.DENY) ) 


<security-constraint> 
<web-resource-collection> 
<url-pattern>...</url-pattern> 
<http-method-omission>TRACE</http-method-omission> 
</web-resource-collection> 
<auth-constraint> 
<role-name>Role1</role-name> 
</auth-constraint> 
</security-constraint> 
<security-constraint> 
<web-resource-collection> 
<url-pattern>...</url-pattern> 
<http-method>TRACE</http-method> 
</web-resource-collection> 
<auth-constraint/> 
</security-constraint> 


映射 @HttpConstraint 和 @HttpMethodConstraint 为 XML 


本 节 将 介绍 映射 映射 @HttpConstraint 和 @HttpMethodConstraint 注解 值 (在 
@ServletSecurity 中 定义 使 用 的 ) 为 它们 等 价 的 auth-constraint 和 user-data-constraint 表 
示 ， 这 些 注解 共用 一 个 通用 模型 用 于 表示 用 在 便携 式 部 署 描述 符 中 的 auth-constraint 和 user- 
data-constraint 元 素 的 等 价 形式 。 该 模型 包括 以 下 3 种 元 素 : 


。 emptyRoleSemantic 授权 语义 ，PERMIT 或 DENY， 适 用 于 在 rolesAllowed 中 没有 指定 的 
角色 时 。 此 元 素 的 默认 值 为 PERMIT， 且 DENY 不 支持 与 非 空 的 rolesAllowed 列 表 结 合 使 
用 。 

e rolesAllowed 一 个 包含 授权 角色 的 名 字 列 表 。 当 该 列表 为 空 时 ， 其 含义 取决 于 
emptyRoleSemantic 的 值 。 当 角色 名 字 “” 包 含 在 允许 的 角色 列表 中 时 是 没有 特别 的 含义 
的 。 当 特殊 的 角色 名 字 “” 出 现在 rolesAllowed 中 时 ， 它 表示 用 户 认 证 ， 不 受 约束 的 角色 ， 


是 必需 的 和 足够 的 。 该 元 素 的 软 认 值 是 一 个 空 列 表 。 

e transportGuarantee 数据 保护 需求 ， NONE 或 CONFIDENTIAL， 在 连接 的 请 求 到 达 时 必 
须 满足 。 该 元 素 与 一 个 包含 一 个 使 用 相应 值 的 transport-guarantee 的 user-data-constraint 
是 等 价 的 。 该 元 素 的 默认 值 是 NONE。 下 面 的 例子 展示 了 上 述 的 @HttpConstraint 模型 
和 web.xml 中 的 auth-constraint 和 user-data-constraint 元 素 之 间 的 对 应 关系 。 


CODE EXAMPLE 13-10 emptyRoleSemantic=PERMIT, rolesAllowed={}, 
transportGuarantee=NONE 


没有 constraint 


CODE EXAMPLE 13-11 emptyRoleSemantic=PERMIT, rolesAllowed={}, 
transportGuarantee=CONFIDENTIAL 


<user -data-constraint> 
<transport-guarantee>CONFIDENTIAL</transport-guarantee> 
</user -data-constraint> 


CODE EXAMPLE 13-12 emptyRoleSemantic=PERMIT, rolesAllowed= 
{Role1},transportGuarantee=NONE 


<auth-constraint> 
<security-role-name>Role1</security-role-name> 
</auth-constraint> 


CODE EXAMPLE 13-13 emptyRoleSemantic=PERMIT, rolesAllowed= 
{Role1},transportGuarantee=CONFIDENTIAL 


<auth-constraint> 
<security-role-name>Role1</security-role-name> 

</auth-constraint> 

<user -data-constraint> 
<transport-guarantee>CONFIDENTIAL</transport-guarantee> 

</user -data-constraint> 


CODE EXAMPLE 13-14 emptyRoleSemantic=DENY, rolesAllowed={}, 
transportGuarantee=NONE 


<auth-constraint/> 


CODE EXAMPLE 13-15 emptyRoleSemantic=DENY, rolesAllowed={}, 
transportGuarantee=CONFIDENTIAL 


<auth-constraint/> 

<user -data-constraint> 
<transport-guarantee>CONFIDENTIAL</transport-guarantee> 

</user -data-constraint> 


ServletRegistration.Dynamic 的 setServletSecurity 


ServietContextListener 内 的 setServletSecurity 方法 用 于 定义 应 用 到 ServletRegistration < 
义 的 映射 的 安全 约束 。 


Collection<String> setServletSecurity(ServletSecurityElement arg); 


setServletSecurity  javax.serviet.ServietSecurityElement 参数 与 ServietSecurity 接口 的 
@ServletSecurity 注解 在 结构 和 模型 上 是 类 似 的 。 因 此 ， 定 义 在 13.4.1.2 节 的 “映射 
@ServletSecurity 为 security-constraint” 的 映射 ， 应 用 类 似 的 包含 HttpConstraintElement 和 
HttpMethodConstraintElement 值 的 ServletSecurityElement 映射 为 其 等 价 的 security- 
constraint 表示 。 


setServietSecurity 方法 返回 一 组 URL pattern (可 能 空 ) ， 其 已 是 便携 式 部 署 描述 符 中 的 
security-constraint 元 素 的 精确 目标 (因此 ， 调 用 是 不 影响 的 ) o 


如 果 ServletContext 中 得 到 的 ServletRegistration 已 经 被 初始 化 了 ， 该 方法 抛 出 
lllegalStateException ° 


当 便 携 式 部 署 描述 符 中 的 security-constraint 包含 一 个 url-pattern 其 精确 匹配 
ServietRegistration 映射 的 pattern， 调 用 ServletRegistration 的 setServletSecurity 必须 对 
Servlet 容器 对 pattern 实施 的 约束 没有 任何 影响 。 


除了 上 面 列 出 的 ， 包 括 当 Servlet 类 注解 了 @ServletSecurity， 当 调用 了 ServletRegistration 
的 setServletSecurity， 它 制定 应 用 到 registration 的 url-pattern 的 安全 约束 。 


角色 


安全 角色 是 由 应 用 开发 人 员 或 装配 人 员 定 义 的 逻辑 用 户 分 组 。 当 部 署 了 应 用 ， 由 部 署 人 员 映 
射 角色 到 运行 时 环境 的 principal 或 组 。 


Servlet 容器 根据 principal 的 安全 属性 为 与 进入 请 求 相关 的 principal 实施 声明 式 或 编程 式 安 
全 。 这 可 能 以 如 下 任 一 方式 发 生 : 

1. 部署 人 员 已 经 映射 一 个 安全 角色 到 运行 环境 中 的 一 个 用 户 组 。 调 用 的 principal 所 属 的 用 
户 组 取 自 其 安全 属性 。 仅 当 principal 所 属 的 用 户 组 由 部 署 人 员 已 经 映射 了 安全 角色 > 
principal 是 在 安全 角色 中 。 

2. 部 署 人 员 已 经 映射 安全 角色 到 安全 策略 域 中 的 principal 名 字 。 在 这 种 情况 下 ， 调 用 的 
principal 的 名 字 取 自 其 安全 属性 。 仅 当 principal 名 字 与 安全 角色 已 映射 到 的 principal 名 
字 一 样 时 ，principal 是 在 安全 角色 中 。 


从 十 
Web 客 户 端 可 以 使 用 以 下 机 制 之 一 向 web 服 务 器 认证 用 户 身份 : 


e HTTP Basic Authentication (HTTP 基 本 认证 ) 

e HTTP Digest Authentication (HTTP 摘 要 认证 ) 

e HTTPS Client Authentication (HTTPS 客 户 端 认证 ) 
e Form Based Authentication (基于 表单 的 认证 ) 


HTTP Basic Authentication 


HTTP Basic Authentication 基于 用 户 名 和 和 密码， 是 HTTP/1.0 规范 中 定义 的 认证 机 制 。Web 

及 务 器 要 求 web 客户 端 认证 用 户 。 作 为 请 求 的 一 部 分 ，web 服务 器 传递 ream (FHF) 4 
mom P ° Web 客户 端 获取 用 户 的 用 户 名 和 密码 并 传 给 web 服务 器 。Web 服务 器 然 
后 在 指定 的 realm 认证 用 户 。 


基本 认证 是 不 安全 的 认证 协议 。 用 户 密码 以 简单 的 base64 编码 发 送 ， 且 未 认证 目标 服务 器 。 
额外 的 保护 可 以 减少 一 些 担忧 : 安全 传输 机 制 (HTTPS) ， 或 者 网 络 层 安全 (如 IPSEC 协议 
或 VPN 策略 ) 被 应 用 到 一 些 部 署 场景 。 


HTTP Digest Authentication 


跟 HTTP Basic Authentication 类 似 ，HTTP Digest Authentication 也 是 基于 用 户 名 和 密码 ， 
所 不 同 的 是 ，HTTP Digest Authentication 并 不 在 网 络 中 传递 用 户 密码 。 在 HTTP Digest 
Authentication 中 ， 客 户 端 发 送 单 向 散 列 的 密码 (和 额外 的 数据 ) 。 尽 管 密码 不 在 线路 上 发 
生 ，HTTP Digest Authentication 需要 对 认证 容器 可 用 的 明文 密码 等 价 物 (密码 等 价 物 可 以 是 
这 样 的 ， 它 们 仅 能 在 一 个 特定 的 realm 用 来 认证 用 户 ) ， 以 致 容器 可 以 通过 计算 预期 的 摘要 
验证 接收 到 的 认证 者 。Servlet 容 器 应 支持 HTTP_DIGEST 身份 认证 。 


Form Based Authentication 


“登录 界面 "的 外 观 在 使 用 web 浏览 器 的 内 置 的 认证 机 制 时 不 能 被 改变 。 本 规范 引入 了 所 需 的 
基于 表单 的 认证 机 制 ， 允 许 开发 人 员 控 制 登 录 界 面 的 外 观 。 


Wd 述 符 包 含 登录 表单 和 错误 页 面条 目 。 登 录 界 面 必须 包含 用 于 输入 用 户 名 和 密 
码 的 字段 。 这 些 字 段 必 须 分 别 命名 为 j_username 和 j password ° 


当 用 户 试 图 访问 一 个 受 保护 的 web 资源 ， 容 器 坚持 用 户 的 认证 。 如 果 用 户 已 经 通过 认证 则 具 


有 访问 资源 的 权限 ， 请 求 的 Web 资源 被 激活 并 返回 一 个 引用 。 如 果 用 户 未 被 认证 ， 发 生 所 有 
如 下 步骤 : 


1. 与 安全 约束 关联 的 登录 界面 被 发 送 到 客户 端 ， 且 URL 路 径 和 HTTP 协议 方法 触发 容器 存 

储 的 认证 。 

用 户 被 要 求 填写 表单 ， 和 包括 用 户 名 和 密码 字段 。 

客户 端 post 表单 到 服务 器 。 

容器 尝试 使 用 来 自 表单 的 信息 认证 用 户 。 

如 果 认 证 失败 ， 使 用 forward 或 redirect 返回 错误 页 面 ， 且 响应 状态 码 设置 为 200。 错 误 

页 面包 含 失败 信息 。 

6， 如 果 授 权 成 功 ， 客 户 端 使 用 存储 的 URL 路 径 重 定向 到 资源 。 

7.， 当 一 个 重 定向 的 和 已 认证 的 请 求 到 达 容 器 ， 容 器 恢复 请 求 和 HTTP h 议 方法 ， 且 已 认证 
的 用 户主 体 被 检查 看 看 是 否 它 在 ere 问 资源 的 角色 中 。 

8. 如 果 用 户 已 授权 ， 容 器 处 理 接受 的 请 求 。 


ak wD 


到 达 步 骤 7 的 重 定向 的 请 求 的 HTTP 协议 方法 ， 可 以 和 触发 认证 的 请 求 有 不 同 的 HTTP 方法 。 
同样 地 ， 在 第 6 步 的 重 定 向 之 后 ， 表 单 认证 器 必须 处 理 重 定向 的 请 求 ， 即 使 对 到 达 请 求 的 
HTTP 方法 的 认证 不 是 必需 的 。 为 了 改善 重 定向 的 请 求 的 HTTP 方法 的 可 预测 性 ， 容 器 应 该 
使 用 303 状 态 码 (SC_SEE_OTHER) 重 定向 〈 步 骤 6) ， 除 了 与 HTTP 1.0 用 户 代 理 的 协作 之 
外 的 是 必需 的 ; 在 这 种 情况 应 该 使 用 302 状 态 码 。 


当 进 行 一 个 不 受 保护 的 传输 时 ， 基 于 表单 的 认证 受制 于 一 些 与 基本 验证 一 样 的 相同 的 脆弱 

小 o 

当 触 发 认证 的 请 求 在 一 个 安全 传输 之 上 到 达 ， 或 者 登录 页 面 TONAL user- 
data-constraint， 登 录 页 面 必须 返回 给 用 户 ， 并 在 安全 传输 之 上 提交 到 容器 


登录 页 面 受 制 于 一 个 CONFIDENTIAL user-data-constraint， 且 一 个 CONFIDENTIAL user- 
data-constraint 应 该 包含 在 每 一 个 包含 认证 要 求 的 security-constraint 中 。 


HttpServletRequest 接口 的 login 方法 提供 另 一 种 用 于 应 用 控制 它 的 登录 界面 外 观 的 手段 。 


登录 表单 


基于 表单 的 登录 和 基于 URL 的 session 跟踪 可 以 通过 编程 实现 。 基 于 表单 的 登录 应 该 仅 被 用 
在 当 session 由 cookie 或 SSL session 信息 维护 时 。 


为 了 进行 适当 的 认证 ， 登 录 表 单 的 action 总 security_check。 该 限制 使 得 不 管 请 求 什么 资 
源 ， 有 登录 表单 都 能 工作 ， 且 避免 了 要 求 服务 器 指定 输出 表单 的 action 字段 。 登 录 表 单 应 该 在 
密码 表单 字段 上 指定 autocomplete="off" 。 


下 面 的 示例 展示 了 如 何 把 表单 编码 到 HTML 页 中 : 


<form method="POST” action="j_security_check”> 

<input type="text” name="j_username"> 

<input type="password” name="j_password" autocomplete="off"> 
</form> 


toR AA HTTP 请 求 造 成 基于 表单 的 登录 被 调用 ， 容 器 必须 保存 原始 请 求 参 数 ， 在 成 功 认 证 
时 使 用 ， 它 重 定向 调用 所 请 求 的 资源 。 


如 果 用 户 已 使 用 表单 登录 通过 认证 ， 且 已 经 创建 一 个 HTTP session， 该 session 的 超时 或 失 
效 将 导致 用 户 被 注销 ， 在 这 种 情况 下 ， 随 后 的 请 求 必须 导致 用 户 重 新 认证 。 注 销 与 认证 具有 
相同 的 作用 域 : 例如 ， 如 果 容 器 支持 单 点 登录 ， 如 Java EE 技术 兼容 的 Web 容器 ， 用 户 只 需 
要 与 托管 在 Web 容 器 中 的 任何 一 个 web 应 用 重新 认证 即 可 。 


HTTPS Client Authentication 


使 用 HTTPS (HTTP over SSL) 认证 最 终 用 户 是 一 种 强 认证 机 制 。 该 机 制 需要 客户 端 拥有 
Public Key Certificate (PKC) 。 目 前 ，PKC 在 电子 商务 应 用 中 是 很 有 用 的 ， 也 对 浏览 器 中 的 
单 点 登录 很 有 用 。 


其 他 容器 认证 机 制 


Servlet 容器 应 该 提供 公共 接口 ， 可 用 于 集成 和 配置 其 他 的 HTTP 消息 层 的 认证 机 制 ， 提 供给 
代表 已 部 署 应 用 的 容器 使 用 。 这 些 接口 应 该 提供 给 参与 者 使 用 而 不 是 容器 供应 商 (包括 应 用 
开发 人 员 、 系 统管 理 人 员 和 系统 集成 人 员 ) o 


为 了 便于 实现 和 集成 其 他 容器 认证 机 制 ， 建 议 为 所 有 Servlet 容器 实现 Servlet 容器 Profile 的 
Java 认证 SPI (PP > JSR 196) 。SPI 可 下 载 地 址 : http://www.jep.org/en/jsr/detail?id=196 


服务 S šk oR IKTE 信 息 


下 面 的 安全 标识 (如 用 户 和 组 ) 在 运行 时 环境 中 映射 的 角色 是 环境 指定 的 而 非 应 用 指定 的 ， 
理想 的 是 : 

1. 使 登录 机 制 和 策略 是 web 应 用 部 署 到 的 环境 属性 。 

2. 在 同一 个 容器 部 署 的 所 有 应 用 能 使 用 相同 的 认证 信息 来 表示 principal， 且 

3， 需 要 重新 认证 用 户 仅 当 已 经 越过 了 安全 策略 域 边界 。 


因此 ，servlet 容器 需要 在 容器 级 别 (而 不 是 在 web 应 用 级 别 ) 跟踪 认证 信息 。 这 允许 在 一 个 
Web 应 用 已 经 通过 认证 的 用 户 可 以 访问 容器 管理 的 以 同样 的 安全 标识 许可 的 其 他 资源 。 


指定 安全 约束 


安全 约束 是 一 种 定义 web 内 容 保护 的 声明 式 方式 。 安 全 约束 关联 授权 和 或 在 web 资源 上 对 
HTTP 操作 的 用 户 数 据 约 束 。 安 全 约束 ， 在 部 署 描述 符 中 由 security-constraint 表示 ， 其 包含 
ULF UE : 


* Web 资 源 集合 (部 署 描述 符 中 的 web-resource-collection) 

© 授权 约束 (部 署 描 述 符 中 的 auth-constraint) 

e 用 户 数 据 约束 (部 署 描述 符 中 的 user-data-constraint) HTTP 操 作 和 网 络 资源 的 安全 约束 
应 用 ( 即 受 限 的 请 求 ) 根 据 一 个 或 多 个 web 资 源 集合 识别 。Web 资 源 集合 包含 以 下 元 素 | 

* URL 模式 (部 署 描 述 符 中 的 url-pattern) 

* HTTP methods (部 署 描述 符 中 的 http-method 或 http-method-omission 元 素 ) 


授权 约束 规定 认证 和 命名 执行 受 约束 请 求 的 被 许可 的 授权 角色 的 要 求 。 用 户 必 须 至 少 是 许可 
执行 受 约束 请 求 的 命名 角色 中 的 一 个 成 员 。 特 殊 角色 名 "…" 是 定义 在 部 署 描述 符 中 的 所 有 角色 名 
的 一 种 简写 。 特 殊 的 角色 名 党 是 一 种 用 于 任何 授权 的 用 户 不 受 约束 的 角色 的 速记 法 。 它 表示 
任何 授权 的 用 户 ， 不 受 约束 的 角色 ， 被 授权 多 许 执行 约束 的 请 求 。 没 有 指定 角色 的 授权 约束 
表示 在 任何 情况 下 不 允许 访问 受 约束 请 求 。 授 权 约 束 包 含 以 下 元 素 : 


e role name (部 署 描述 符 中 的 role-name) 


用 户 数 据 约束 规定 了 在 受 保护 的 传输 层 连 接 之 上 接收 受 约束 的 请 求 的 要 求 。 需 要 保护 的 强度 
由 传输 保障 的 值 定义 。INTEGRAL 类 型 的 传输 保障 用 于 规定 内 容 完 整 性 要 求 ， 且 传输 保障 
CONFIDENTIAL 用 于 规定 保密 性 要 求 的 。 传 输 保障 “NONE” 表 示 当 容器 通过 任何 包括 不 受 保护 
的 连接 接受 到 请 求 时 ， 必 须 接 受 此 受 约束 的 请 求 。 容 器 可 能 在 响应 中 强加 一 个 受信 的 传输 保 
障 (confidential transport guarantee) 为 INTEGRAL 值 。 用户 数 据 约束 包括 如 下 元 素 : 


e transport guarantee (部 署 描述 符 中 的 transport-guarantee) 


如 果 没 有 授权 约束 应 用 到 请 求 ， 容 器 必须 接受 请 求 ， 而 不 要 求 用 户 身份 认证 。 如 果 没 有 用 户 
数据 约束 应 用 到 请 求 ， 当 容器 通过 任何 包括 不 受 保护 的 连接 接收 到 请 求 时 ， 必 须 接 受 此 请 


组 合约 束 


为 了 组 合约 束 ，HTTP 方法 可 以 说 是 存在 于 web-resource-collection 中 ， 仅 当 没 有 在 集合 中 指 
Z HTTP 方法 ， 或 者 集合 在 包含 的 http-method 元 素 中 具体 指定 了 HTTP 方法 ， 或 者 集合 包 
含 一 个 或 多 个 http-method-omission 元 素 ， 但 那些 没有 指定 的 HTTP 方法 。 当 url-pattern 和 
HTTP 方法 以 组 合 方式 ( 即 ， 在 Web-resource-collection 中 ) 出 现在 多 个 安全 约束 中 ， 该 约 
束 (在 模式 和 方法 上 的 ) 是 通过 合并 单个 约束 定义 的 。 以 相同 的 模式 和 方法 出 现 的 组 合约 束 
规则 如 下 所 示 : 


授权 约束 组 合 ， 其 明确 指定 角色 或 通过 “” 隐 人 式 指定 角色 ， 可 产生 单个 约束 的 合并 的 角色 名 称 
作为 许可 的 角色 。 一 个 命名 角色 “” 的 授权 约束 将 与 授权 约束 命名 的 或 隐 式 的 角色 组 合 以 允许 
任何 授权 的 用 户 不 受 约束 的 角色 。 不 包含 授权 约束 的 安全 约束 将 与 明确 指定 角色 的 或 隐 式 指 
定 角 色 的 允许 未 授权 访问 的 安全 约束 合并 。 授 权 约 束 的 一 个 特殊 情况 是 其 没有 指定 角色 ， 将 
与 任何 其 他 约束 合并 并 覆盖 它们 的 作用 ， 这 导致 访问 被 阻止 。 


应 用 到 常见 的 url-pattern 和 http-method 的 user-data-constraint 组 合 ， 可 产生 合并 的 单个 约 
束 接 受 的 连接 类 型 作为 接受 的 连接 类 型 。 不 包含 user-data-constraint 的 安全 约束 ， 将 与 其 他 
user-data-constraint 合并 ， 使 不 安全 的 连接 类 型 是 可 接受 的 连接 类 型 。 


示例 


下 面 的 示例 演示 了 组 合约 束 及 它们 翻译 到 的 可 应 用 的 约束 表格 。 假 设 部 署 描述 符 包 含 如 下 安 
BBR © 


<security-constraint> 
<web-resource-collection> 
<web-resource-name>precluded methods</web-resource-name> 
<url-pattern>/*</url-pattern> 
<url-pattern>/acme/wholesale/*</url-pattern> 
<url-pattern>/acme/retail/*</url-pattern> 
<http-method-omission>GET</http-method-omission> 
<http-method-omission>POST</http-method-omission> 
</web-resource-collection> 
<auth-constraint/> 
</security-constraint> 
<security-constraint> 
<web-resource-collection> 
<web-resource-name>wholesale</web-resource-name> 
<url-pattern>/acme/wholesale/*</url-pattern> 
<http-method>GET</http-method> 
<http-method>PUT</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>SALESCLERK</role-name> 
</auth-constraint> 
</security-constraint> 
<security-constraint> 
<web-resource-collection> 
<web-resource-name>wholesale 2</web-resource-name> 
<url-pattern>/acme/wholesale/*</url-pattern> 
<http-method>GET</http-method> 
<http-method>POST</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>CONTRACTOR</role-name> 
</auth-constraint> 
<user-data-constraint> 
<transport-guarantee>CONFIDENTIAL</transport-guarantee> 
</user -data-constraint> 
</security-constraint> 
<security-constraint> 
<web-resource-collection> 
<web-resource-name>retail</web-resource-name> 
<url-pattern>/acme/retail/*</url-pattern> 
<http-method>GET</http-method> 
<http-method>POST</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>CONTRACTOR</role-name> 
<role-name>HOMEOWNER</role-name> 
</auth-constraint> 
</security-constraint> 


转化 这 个 假定 的 部 署 描述 符 将 产生 定义 在 表 13-4 中 的 约束 。 


TABLE 13-4 Security Constraint Table 








url-pattern http 方法 许可 的 角色 支持 的 连接 类 型 
r ds reda 阻止 访问 不 限制 
/acme/wholesale/* als ae 2 阻止 访问 不 限制 
/acme/wholesale/ = GET jE kaaa 不 限制 
/acme/wholesale/* POST CONTRACTOR CONFIDENTIAL 
/acme/retail/* ls me : 阻止 访问 不 限制 
/acme/retail/* GET SOMES = a 不 限制 
/acme/retail/* POST EE = dh 不 限制 


处 理 请 求 


4 servlet 容器 接收 到 一 个 请 求 ， 它 将 使 用 119 页 "使 用 URL 路 径 ?描述 的 规则 来 选择 在 请 求 URI 
最 佳 匹 配 的 Url-pattern 上 定义 的 约束 (如 果 有 ) 。 如 果 没 有 约束 被 选择 ， 容 器 将 接受 该 请 求 。 

和 否则， 容器 将 确定 在 选择 的 模式 上 是 否 此 请 求 的 HTTP 方 法 是 受 约束 的 。 如 果 不 是 ， 请 求 将 被 
接受 。 否 则 ， 请 求 必须 满足 在 urlpattern 应 用 到 HTTP 方 法 的 约束 。 请 求 被 接受 和 分 派 到 相关 的 
servlet， 必 须 满足 以 下 两 个 规则 。 


1. 接收 到 的 请 求 的 连接 特性 必须 满足 至 少 一 种 由 约束 定义 的 支持 的 连接 类 型 。 如 果 该 规则 
不 满足 ， 容 器 将 拒绝 该 请 求 并 重 定向 到 HTTPS 端 口 。 (作为 一 种 优化 ， 容 器 将 以 拒绝 该 
请 求 为 forbidden 并 返回 403 (SC_FORBIDDEN) 状 态 码 ， 如 果 知 道 该 访问 将 最 终 将 被 阻止 
(通过 没有 指定 角色 的 授权 约束 ) ) 

2. 请 求 的 认证 特性 必须 满足 任何 由 约束 定义 的 认证 和 角色 要 求 。 如 果 该 规则 不 能 满足 是 因 
为 访问 已 经 被 阻止 (通过 没有 指定 角色 的 授权 约束 ) ， 则 请 求 将 被 拒绝 为 forbidden 并 返 
回 403 (SC_FORBIDDEN) 状 态 码 。 如 果 访 问 是 受 限于 许可 的 角色 且 请 求 还 没有 被 认证 ， 
则 请 求 将 被 拒绝 为 unauthorized 且 401(SC_UNAUTHORIZED) 状 态 码 将 被 返回 以 导致 身 
份 认证 。 如 果 访 问 是 受 限于 许可 的 角色 且 请 求 的 认证 身份 不 是 这 些 角色 中 的 成 员 ， 则 请 
求 将 被 拒绝 为 forbidden 且 403 状 态 码 (SC_FORBIDDEN) 将 被 返回 到 用 户 。 


ABS HTTP 协议 方法 


security-constraint schema 提 供 了 枚 举 ( 包括 省 略 ) 定义 在 security-constraint 中 的 保护 要 求 
应 用 到 哪 一 个 HTTP 方 法 的 能 力 。 当 HTTP 方法 枚 举 在 security-constraint， 约 束 定义 的 保护 仅 
应 用 到 枚 举 建 立 的 方法 。 我 们 把 不 是 枚 举 建立 的 方法 称 为 "未 履 盖 的 "HTTP 方 法 。 未 履 盖 的 
HTTP 方法 不 保护 所 有 security-constraint 的 url-pattern 最 匹配 的 请 求 的 URL 。 


当 HTTP 方法 没有 枚 举 在 一 个 security-constraint 中 时 ， 约 束 定义 的 保护 应 用 到 完整 的 
HTTP (扩展 ) 方法 集 。 在 那 种 情况 ， 在 那些 security-constraint 的 url-pattern 最 佳 匹 配 的 所 有 
请 求 的 URL， 没 有 未 履 盖 的 HTTP 方 法 。 


例子 用 三 种 方式 描述 了 在 哪些 HTTP 协议 方法 可 能 未 履 盖 。 方 法 是 否 是 未 敌 盖 的 是 由 在 所 有 
约束 应 用 到 一 个 url-pattern 已 经 按照 113.8.1 节 ，“ 组 合约 束 " 组 合 决定 的 。 


1. security-constraint 在 http-method 元 素 中 命名 一 个 或 多 个 HTTP 方法 。 除 了 那些 明明 在 
约束 中 的 ， 所 有 HTTP ZRAKA žig o 


<web-resource-collection> 
<web-resource-name>wholesale</web-resource-name> 
<url-pattern>/acme/wholesale/*</url-pattern> 
<http-method>GET</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>SALESCLERK</role-name> 
</auth-constraint> 


</security-constraint> 
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<web-resource-collection> 
<web- resource -name>wholesale</web -resource-name> 
<url-pattern>/acme/wholesale/*</url-pattern> 
<http-method-omission>GET</http-method-omission> 

</web-resource-collection> 

<auth-constraint/> 


</security-constraint> 


GETE AA 24 > MA HUA ik A RBE  auth-constraint® % %4 o 


1. 包括 一 个 @HttpConstraint 的 @ServletSecurity 注解 返回 所 有 默认 值 ， 且 也 包括 至 少 一 
个 返回 除了 所 有 默认 值 之 外 的 @HttpMethodConstraint。 除 了 那些 命名 在 
@HttpMethodConstraint 中 的 所 有 HTTP 方法 是 被 注解 未 和 覆盖 的 。 这 种 情况 是 与 情况 1 是 


类 似 的 ， 且 等 价 于 使 用 ServietRegistration 接口 的 setServietSecurity 方法 也 将 产生 一 个 
类 似 的 结果 。 


@ServletSecurity((httpMethodConstraints = { @HttpMethodConstraint(value = "GET", 
rolesAllowed = "R1"), @HttpMethodConstraint(value = "POST", rolesAllowed = "R1", 
transportGuarantee = TransportGuarantee.CONFIDENTIAL) }) public class Example5 
extends HttpServlet { } 


除了 GET 和 POST 之 外 的 所 有 HTTP 方 法 是 未 履 盖 的 。 


安全 约束 配置 规则 
目的 : 确保 在 所 有 约束 的 URL 模式 上 的 所 有 HTTP 方 法 有 预期 的 安全 保护 (BP > RAHN) © 


1. 没有 在 约束 中 命名 HTTP 方法 ; 在 这 种 情况 下 ， 未 URL 模式 定义 的 安全 保护 将 应 用 到 所 
有 HTTP 方法 。 

2. 如果 你 不 能 遵循 规则 #1， 添 加 <deny-uncovered-http-methods> 和 声明 (使 用 <http- 
method> 元 素 ， 或 等 价 的 注解 ) 所 有 在 约束 URL 模 式 允许 的 HTTP 方 法 (有 安全 保护 ) 。 

3. 如果 你 不 能 遵循 规则 #2， 声 明 约 束 来 覆盖 每 一 个 约束 的 URL 模 式 的 所 有 HTTP 方 法 。 使 
用 <http-method-omission> 元 素 或 HttpMethodConstraint 注解 来 表示 除了 被 <http- 
method> 或 HttpMethodConstraint 命名 的 那些 之 外 的 所 有 HTTP 方法 集 。 当 使 用 注解 时 ， 
使 用 HttpConstraint 定义 应 用 到 所 有 其 他 HTTP 方法 和 配置 EmptyRoleSemantic=DENY 
来 导致 所 有 其 他 HTTP 方法 被 拒绝 的 安全 语义 。 


处 理 未 履 盖 的 HTTP 方 法 


在 应 用 部 署 期 间 ， 容 器 必须 通知 部 署 人 员 任 何 存在 于 从 为 应 用 定义 的 约束 组 合 产生 的 应 用 安 
全 约束 配置 中 的 未 覆盖 的 HTTP 方法 。 提 供 的 信息 必须 标识 未 履 盖 的 HTTP 协议 方法 ， 和 在 
HTTP 方法 未 覆盖 那些 相关 的 URL 模 式 。 通 知 部 署 人 员 的 要 求 可 以 通过 记录 必需 的 信息 来 满 
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4 deny-uncovered-http-methods 标记 在 应 用 的 web.xml 中 设置 了 ， 容 器 必须 拒绝 任何 
HTTP 协议 方法 ， 当 它 用 于 一 个 其 HTTP 方法 在 应 用 到 请 求 URL 最 佳 匹 配 的 url-pattern 的 组 
合 安 全 约束 请 求 URL 是 未 覆盖 的 。 拒 绝 的 请 求 将 被 拒绝 为 forbidden 并 返回 一 个 

403 (SC_FORBIDDEN) 状态 码 。 


导致 未 覆盖 的 HTTP 方法 为 拒绝 ， 部 署 系统 将 建立 额外 的 排除 auth-constraint， 去 履 盖 这 些 
在 未 履 盖 的 HTTP 方 法 约束 的 url-pattern 的 HTTP 方法 。 


当 应 用 的 安全 配置 不 包含 未 履 盖 的 方法 ，deny-uncovered-http-methods 标 记 在 应 用 的 有 效 的 
安全 配置 上 必须 没有 效果 。 


Fz Fil deny-uncovered-http-methods 到 一 个 应 用 ， 其 安全 配置 包含 未 覆盖 的 方法 ， 可 能 ， 在 一 
些 情况 下 ， 拒 绝 访问 资源 为 了 应 用 的 功能 必须 是 可 访问 的 。 这 这 种 情况 下 ， 应 用 的 安全 配置 
应 该 完成 所 有 未 履 盖 的 方法 被 相关 约束 配置 履 盖 。 


应 用 开发 人 员 应 该 定义 安全 约 东 配置， 没有 任何 未 履 盖 的 HTTP 方法 ， 且 他 们 应 该 设置 deny- 
uncovered-http-methods 标记 确保 他 们 的 应 用 不 会 依赖 于 通过 未 履 盖 的 方法 来 得 到 可 访问 
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Servlet 容器 可 以 提供 一 个 配置 选项 来 选择 未 履 盖 方法 的 默认 行为 是 ALLOW 还 是 DENY。 这 
个 选项 可 以 配置 在 每 容器 粒度 或 更 大 。 注 意 ， 设 置 这 个 默认 为 DENY 可 能 导致 一 些 应 用 失 
M o 


默认 策略 


默认 情况 下 ， 身 份 认证 并 不 需要 访问 资源 。 当 安全 约束 (如果 有 ) 包含 的 url-pattern 是 请 求 
URI 的 最 佳 匹 配 ， 且 结合 了 施加 在 请 求 的 HTTP 方法 上 的 auth-constraint (指定 的 角色 ) ， 
则 身份 认证 是 需要 的 。 同 样 ， 一 个 受 保护 的 传输 是 不 需要 的 ， 除 非 应 用 到 请 求 的 安全 约束 结 
合 了 施加 在 请 求 的 HTTP 方 法 上 的 user-data-constraint (有 一 个 受 保护 的 transport- 


guarantee) 。 


登录 和 和 登 出 


容器 在 分 派 请 求 到 servlet 引 敬之 前 建立 调用 者 身份 。 在 整个 请 求 处 理 过 程 中 或 直到 应 用 成 功 
的 在 请 求 上 调用 身份 认证 、 登 录 或 退出 ， 调 用 者 身份 保持 不 变 。 对 于 异步 请 求 ， 调 用 者 身份 
建立 在 初始 分 派 时 ， 直 到 整个 请 求 处 理 完成 或 直到 应 用 成 功 的 在 请 求 上 调用 身份 认证 、 登 录 
或 退出 ， 调 用 者 身份 保持 不 变 。 


在 处 理 请 求 时 登录 到 一 个 应 用 ， 和 
可 以 通过 调用 请 求 的 getRemoteUser 或 getUserPrincipal 确定 。 这 些 方 法 的 任何 一 个 返回 null 
值 表示 调用 者 没有 登录 到 处 理 请 求 的 应 用 。 


容器 可 以 创建 HTTP Session 对 象 用 于 跟踪 登录 状态 。 如 果 开 发 人 员 创 建 一 个 session 而 用 户 
没有 进行 身份 认证 ， 然 后 容器 认证 用 户 ， 登 录 后 ， 对 开发 人 员 代 码 可 见 的 session 必须 是 相 
同 的 session 对象， 该 session 是 登录 发 生 之 前 创建 的 ， 以 便 不 丢失 session 信息 。 


部 署 描述 符 


本 章 指 定 的 Java™ Servlet 规范 要 求 Web 容器 支持 部 署 描述 文件 。 部 署 描述 文件 表达 了 应 用 
开发 人 员 、 应 用 集成 人 员 和 Web 应 用 部 署 人 员 之 间 的 元 素 和 配置 信息 。 


对 于 Java Servlet 2.4 和 以 后 的 版 本 ， 部 署 描述 文件 在 XML 模式 文档 中 定义 。 


为 了 向 后 兼容 到 2.2 版 本 的 API 编 写 的 应 用 程序 ，Web 容器 也 需要 支持 2.2 版 本 的 部 署 描述 文 
件 。 为 了 向 后 兼容 2.3 版 本 的 API 编 写 的 应 用 程序 ，Web 容 器 也 需要 支持 2.3 版 本 的 部 署 描述 文 
件 。2.2 版 本 的 部 署 描述 文件 可 在 此 下 载 : http://java.sun.com/j2ee/dtds/web-app_2 2.dtd > 
2.3 版 本 的 部 署 描述 文件 可 在 此 下 载 : http://java.sun.com/dtd/web-app_2_3.dtd ° 


立 abot a 
部 署 描述 符 元 素 
所 有 servlet 容 器 的 Web 应 用 程序 部 署 描述 文件 需要 支持 以 下 类 型 的 配置 和 部 署 信息 : 


e ServletContext 初 始 化 参数 

e Session 配 置 

。 Servlet 声 明 

e Servlet 映 射 

。 应 用 程序 生命 周期 监听 器 类 

o 过 滤器 定义 和 过 滤器 映射 

。 MIME 类 型 映射 

e 欢迎 文件 列表 

e. 错误 页 面 

o 语言 环境 和 编码 映射 

e 安全 配置 ， 包 括 login-config，security-constraint > security-constraint > security-role-ref 
和 run-as 


处 理 部 署 描述 符 的 规则 


本 节 列 出 了 一 些 通用 的 规则 ，Web 容器 和 开发 人 员 必 须 注意 有 关 Web 应 用 程序 部 署 描述 文件 
的 处 理 。 


e. 对 于 部 署 描述 文件 的 文本 节点 元 素 内 容 ，Web 容器 必须 删除 所 有 前 导 和 后 置 空 格 ， 空 格 
在 XML 1.0“ (http://www.w3.org/TR/2000/WD-xml-2e-20000814) 中 被 定义 为 “S(white 
space)” ° 

o 部 署 描述 文件 对 模式 来 说 必须 是 有 效 的 。Web 容器 和 操作 Web 应 用 程序 的 工具 对 检查 
WAR 文件 的 有 效 性 有 多 种 选择 。 包 括 检查 WAR 文件 中 部 署 描述 文件 的 有 效 性 。* 此 
外 ， 推 荐 Web 容器 和 操作 Web 应 用 程序 的 工具 提供 一 个 级 别 的 语义 检查 。 例 如 ， 应 该 
检查 安全 约束 中 引用 的 角色 和 部 署 描述 文件 中 定义 的 某 个 安全 角色 具有 相同 的 名 称 。 


在 Web 应 用 程序 不 符合 规范 的 情况 下 ， 工 具 和 容器 应 该 用 描述 性 的 错误 消息 告知 开发 人 员 。 
鼓励 高 端 应 用 服务 器 提供 商都 提供 这 种 有 效 性 检查 ， 以 工具 的 形式 和 容器 分 开 。 


e 这 个 版 本 的 规范 中 ，web-app 的 子 元 素 的 顺序 可 以 是 任意 的 。 由 于 XML 模式 的 限制 ， 

分 发 元 素 多 样 性 ，session-config、welcome-file-list、jsp-config 、|ogin-config ee. 

encoding-mapping-list， 从 “可 选 的 " 变 成 “0 个 或 多 个 "。 当 部 署 描述 文件 包含 多 个 session- 

config、jsp-config 和 login-config 时 ， 容 器 必须 用 描述 性 的 错误 消息 告知 开发 人 员 。 当 

eal 容器 必须 连接 welcome-file-list 和 locale-encoding-mapping-list 中 的 项 
可 分 发 的 事件 必须 与 单个 可 分 发 的 事件 以 同样 的 方式 正确 对 待 。 

° e 定 的 URI 路 径 通 过 URL 解 码 形式 (意思 是 已 经 对 URL 进 行 了 转 
SL) 。 当 URL &4 CR(#xD) ( 回 车 ) 或 LF(#xA) (换行 ) 时 ， 容 器 必须 用 描述 性 的 错误 
消息 告知 开发 人 员 。 容 器 必须 保存 所 有 其 他 字符 ， 包 括 URL 中 的 空格 。 

© 容器 必须 尝试 规范 化 部 署 描 文 件 中 的 路 径 。 例 如 ，/a/../b 形 式 的 路 径 必 须 解 释 为 /b。 部 署 
描述 文件 中 以 ../ 开 始 的 路 径 或 解析 成 以 ../ 开 始 的 路 径 都 不 是 有 效 的 路 径 。 

e URI 路 径 指 的 是 相对 于 WAR 文 件 的 根 目 录 ， 或 相对 于 WAR 文 件 的 根 目 录 的 一 个 路 径 映 
射 ， 除 非 另 有 规定 ， 应 以 /开头 。 

© 元 素 的 值 是 一 个 枚 举 类 型 ， 其 值 是 区 分 大 小 写 的 。 


部 署 描述 符 


这 个 版 本 规范 的 部 署 描述 文件 可 在 此 下 载 : http://xmlns.jcp.org/xml/ns/javaee/web- 
app_3_1.xsd 
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部 署 描述 符 图 解 

本 节 举 例 说 明 部 署 描述 文件 中 的 元 素 。 属 性 没有 在 图 中 显示 。 详 细 信 息 请 参阅 部 署 描述 文件 
模式 。 

1.web-app 元 素 


web-app 元 素 是 一 个 Web 应 用 程序 的 根部 署 描述 符 。 此 元 素 包 含 下 列 元 素 。 这 个 元 素 有 一 个 
必需 的 属性 version 来 指定 部 署 描述 符 符 合 哪 个 版 本 的 模式 。 此 元 素 的 所 有 子 元 素 可 以 是 任意 
的 顺序 。 


FIGURE 14-1 web-app Element Structure 


2.description 元 素 


description 元 素 提 供 了 父 元 素 的 文本 描述 。 此 元 素 不 仅 出 现在 web-app 元 素 中 ， 其 他 很 多 元 素 
中 也 有 。 它 有 一 个 可 选 属性 xml:lang 指 明 描 述 中 使 用 哪 一 种 语言 。 该 属性 的 默认 值 是 美语 
(“en”) 。 


3.display-name = # 


display-name 元 素 包 含 一 个 简短 的 名 称 ， 目 的 是 通过 工具 显示 。 显 示 名 称 不 必 是 唯一 的 。 这 
个 元 素 有 一 个 可 选 属性 Xml:lang 用 于 指定 语言 。 


4.icon 元 素 


icon 元 素 包 含 small-icon 和 large-icon 元 素 ， 为 大 型 和 小 型 GIF 或 JPEG 图 标 图 片 指定 文件 名 ， 
用 于 在 GUI 工具 中 表示 父 元 素 。 


5.distributable 元 素 

distributable 元 素 表示 设 定 该 Web 应 用 程序 适合 部 署 到 一 个 分 布 式 的 servlet 容器 中 。 
6.context-param 元 素 

context-param 元 素 包 含 了 Web 应 用 程序 的 servlet 上 下 文 初始 化 参数 的 声明 。 
7.filter 元 素 


filter 元 素 声 明了 Web 应 用 程序 中 的 过 滤器 。 该 过 滤器 映射 到 一 个 servlet 或 filter-mapping 元 素 中 
的 一 个 URL 模 式 ， 使 用 filter-name 的 值 来 引用 。 过 滤器 在 运行 时 可 以 通过 FilterConfig 接 口 访问 
部 署 描述 文件 中 声明 的 初始 化 参数 。filter-name 元 素 是 过 滤器 的 逻辑 名 称 。 它 在 Web 应 用 程序 


中 必须 是 唯一 的 。filter-name 元 素 的 元 素 内 容 不 能 为 空 。filter-class 是 过 滤器 的 完全 限定 类 
名 。init-param 元 素 包 含 的 名 值 对 作为 此 过 滤器 的 初始 化 参数 。 当 指定 可 选 的 async-supported 
元 素 时 ， 表 示 该 过 滤器 支持 异步 请 求 处 理 。 


FIGURE 14-2 filter Element Structure 


8.filter-mapping zu # 


容器 使 用 filter-mapping 决 定 哪 个 过 滤器 以 什么 样 的 顺序 应 用 到 请 求 。filter-name 的 值 必 须 是 部 
署 描述 文件 中 声明 的 过 滤器 中 的 一 个 。 匹 配 的 请 求 可 以 被 指定 为 url-pattern 或 servlet-name。 


FIGURE 14-3 filter-mapping Element Structure 


9. listener. & 


listener 表 示 应 用 程序 监听 器 bean 的 部 署 属性 。 子 元 素 listener-class 声 明 应 用 程序 中 的 一 个 类 
必须 注册 为 Web 应 用 程序 监听 器 bean。 它 的 值 是 监听 器 类 的 完全 限定 类 名 。 


FIGURE 14-4 listener Element Structure 


10.servlet 元 素 


servlet 元 素 用 于 声明 一 个 servlet。 它 包含 一 个 servlet 的 声明 性 数据 。jsp-file 元 素 包 含 到 以 “1" 开 
头 的 Web 应 用 程序 中 一 个 JSP 文 件 的 完全 路 径 。 如 果 指 定 了 jsp-file 并 且 存 在 load-on-start 元 

素 ， 那 么 JSP 应 该 被 预 编译 和 加 载 。servlet-name 元 素 包 含 了 servlet 的 规范 名 称 。 在 Web 应 用 
程序 中 每 个 servlet 的 名 称 是 唯一 的 。servlet-name 元 素 内 容 不 能 为 空 。servlet-class 包 含 了 
servlet 的 完全 限定 类 名 。run-as 元 素 指定 用 作 一 个 组 件 执行 的 标识 。 它 包含 一 个 可 选 的 
description， 和 一 个 由 role-name 元 素 指 定安 全 角色 。|load-on-startup 元 素 表 示 该 servlet 应 该 
在 Web 应 用 程序 启动 时 加 载 (实例 化 并 调用 它 的 init() 方 法 ) 。 该 元 素 的 元 素 内 容 必 须 是 一 个 
整数 ， 表 示 Sservlet 应 该 被 加 载 的 顺序 。 如 果 该 值 是 一 个 负 整数 ， 或 不 存在 该 元 素 ， 容 器 自由 
选择 什么 时 候 加 载 这 个 servlet。 如 果 该 值 是 一 个 正 整 数 或 0， 当 应 用 部 署 后 容器 必须 加 载 和 初 
始 化 这 个 servlet。 容 器 必须 保证 较 小 整数 标记 的 servlet 在 较 大 整数 标记 的 servlet 之 前 加 载 。 容 
器 可 以 选择 具有 相同 load-on-startup 值 的 servlet 的 加 载 顺 序 。security-role-ref 元 素 声 明 组 件 中 
或 部 署 组 件 的 代码 中 的 安全 角色 引用 。 它 由 一 个 可 选 的 description， 在 代码 中 使 用 的 安全 角色 
名 称 (role-name) ， 以 及 一 个 可 选 的 到 一 个 安全 角色 (role-link) 的 链接 组 成 。 如 果 没 有 指 
定安 全 角色 ， 部 署 器 必须 选择 一 个 合适 的 安全 角色 。 当 指定 了 可 选 的 async-supported 元 素 ， 
指示 的 servlet 可 以 支持 异步 请 求 处 理 。 如 果 一 个 servlet 支持 文件 上 传 功 能 和 mime-multipart 请 
求 处 理 ， 通 过 描述 文件 中 的 multipart-config 元 素 能 够 提供 相同 的 配置 。multipart-config 元 素 可 
用 于 指定 文件 存储 的 位 置 ， 上 传 文件 大 小 的 最 大 值 ， 最 大 请 求 大 小 和 文件 将 写 入 磁盘 之 后 的 
RK} BY AB o 


FIGURE 14-5 servlet Element Structure 


11.servlet-mapping i € 
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FIGURE 14-6 servlet-mapping Element Structure 


12.session-config# 


session-config 元 素 定 义 了 该 Web 应 用 程序 的 会 话 参数 。 子 元 素 session-timeout 定 义 了 该 Web 
应 用 程序 中 创建 的 所 有 会 话 的 默认 超时 时 间 间 隔 。 指 定 的 超时 时 间 必 须 使 用 分 钟 数 表 示 。 如 
果 超 时 时 间 小 于 或 等 于 0， 容 器 将 确保 会 话 的 默认 行为 永远 不 会 超时 。 如 果 没 有 指定 这 个 元 
素 ， 容 器 必须 设置 它 的 缺 省 超时 期 限 。 


FIGURE 14-7 session-config Element Structure 


13.mime-mapping 元 素 


mime-mapping 定 义 了 扩展 名 和 MIME 类 型 之 间 的 映射 。extension 元 素 包 含 一 个 字符 串 描 述 的 
扩展 名 ， 例 如 “txt”。 


FIGURE 14-8 mime-mapping Element Structure 


14.welcome-file-list 元 素 


welcome-file-list 包 含 了 一 个 有 序 的 欢迎 文件 列表 。 子 元 素 welcome-file 包 含 一 个 用 作 缺 省 欢迎 
文件 的 文件 名 ， 如 index.html 


FIGURE 14-9 welcome-file-list Element Structure 


15.error-page. € 

error-page 包含 一 个 错误 代码 或 异常 类 型 到 Web 应 用 程序 中 资源 的 路 径 之 间 的 映射 。 不 过 ， 
error-code 或 exception-type 元 素 可 以 省 咯 来 指定 一 个 默认 的 错误 页 面 。 子 元 素 exception-type 
包含 了 一 个 Java 异 常 类 型 的 完全 限定 名 称 。 子 元 素 location 包含 了 web 应 用 程序 中 相对 于 web 
应 用 程序 根 目录 的 资源 位 置 。location 的 值 必 须 以 /开头 。 


FIGURE 14-10 error-page Element Structure 


16.jsp-config Element 


jsp-config 用 来 提供 Web 应 用 程序 中 的 JSP 文 件 的 全 局 配置 信息 。 它 有 两 个 子 元 素 ，taglib 和 
jsp-property-group。taglib 元 素 可 用 来 为 Web 应 用 程序 中 的 JSP 页 面 使 用 的 标签 库 提供 信息 。 
详细 信息 请 参阅 JavaServer Pages 规 范 2.1 版 本 。 


FIGURE 14-11 jsp-config Element Structure 


17.security-constraint 元 素 


security-constraint 用 于 关联 安全 约束 和 一 个 或 多 个 Web 资 源 集合 。 子 元 素 web-resource- 
collection 确 定安 全 约束 应 用 到 哪 一 些 Web 应 用 程序 中 资源 的 子 集 和 这 些 资源 的 HTTP 方 法 。 
auth-constraint 表 示 用 户 角色 应 该 允许 访问 此 资源 集合 。 这 里 使 用 的 role-name 必 须 与 该 Web 
应 用 程序 定义 的 其 中 一 个 security-role 元 素 的 role-name 对 应 ， 或 者 是 指定 的 保留 role- 
name"” 对 应 ， 这 是 一 个 表示 Web 应 用 程序 中 的 所 有 角色 的 紧凑 语法 。 如 果 ” 和 角色 名 都 出 现 
了 ， 容 器 会 将 此 解释 为 所 有 角色 。 如 果 没 有 定义 角色 ， 不 允许 任何 用 户 访问 由 包含 security- 
constraint 所 描述 的 Web 应 用 程序 的 部 分 。 当 容器 确定 访问 时 匹配 角色 名 称 是 区 分 大 小 写 的 。 
user-data-constraint 表 示 客 户 端 和 容器 之 间 的 通信 数据 如 何 受 到 子 元 素 transport-guarantee 的 
保护 。transport-guarantee 的 合法 值 是 NONE，INTEGRAL 或 CONFIDENTIAL 之 一 。 


FIGURE 14-12 security-constraint Element Structure 


18.login-config 元 素 


login-config 用 于 配置 应 该 使 用 的 验证 方法 ， 可 用 于 此 应 用 程序 的 领域 名 ， 以 及 表单 登录 机 制 
所 需要 的 属性 。 子 元 素 auth-method 为 Web 应 用 程序 配置 验证 机 制 。 该 元 素 的 内 容 必 须 是 
BASIC ` DIGEST ` FORM 、CLIENT-CERT、 或 vendor-specific 验 证 模式 。realm-name 表 示 
为 Web 应 用 程序 选择 用 于 验证 模式 的 领域 名 。form-login-config 指 定 应 该 用 于 基于 表单 登录 的 
登录 和 错误 页 面 。 如 果 不 使 用 基于 表单 的 登录 方式 ， 这 些 元 素 将 被 忽略 。 


FIGURE 14-13 login-config Element Structure 


19.security-role 元 素 


security-role 定 义 了 一 个 安全 角色 。 子 元 素 role-name 指 定安 全 角色 的 名 称 。 该 名 称 必 须 符 合 
NMTOKEN 的 词法 规则 。 


FIGURE 14-14 security-role Element Structure 


20.env-entry 元 素 


env-entry 声 明了 一 个 应 用 程序 的 环境 入 口 。 子 元 素 env-entry-name 包 含 部署 组 件 环 境 入 口 的 
名 称 。 这 个 名 称 是 一 个 相对 于 java:comp/env 上 下 文 的 JNDI 名 称 。 在 部 署 组 件 中 该 名 称 必须 是 
唯一 的 。env-entry-type 包 含 了 应 用 程序 代码 所 期 望 的 环境 入 口 值 的 Java 类 型 完全 限定 名 。 子 
元 素 env-entry-value 指 定 部 署 组 件 的 环境 入 口 值 。 该 值 必须 是 一 个 String， 对 指定 的 使 用 一 个 
String 或 java.lang.Character 类 型 作为 参数 的 构造 器 有 效 。 可 选 的 injection-target 元 素 用 来 定义 
把 指定 的 资源 注入 到 字段 或 JavaBean 属 性 。injection-target 指 定 了 类 中 应 该 被 注入 资源 的 类 
和 名 称 。injection-target-class 指 定 了 注入 目标 的 完全 限定 类 名 称 。injection-target-name 指 定 
了 指定 类 中 的 目标 。 首 先 把 查找 目标 作为 一 个 JavaBean 属 性 名 称 。 如 果 没 有 找到 ， 则 把 查找 
目标 作为 一 个 字段 名 。 在 类 初始 化 期 间 通 过 调用 目标 属性 的 set 方 法 或 给 名 称 字 段 设置 一 个 值 
将 指定 的 资源 注入 到 目标 。 如 果 环 境 入 口 指定 了 一 个 injection-target， 那 么 env-entry-type 可 
以 省 略 或 必须 与 注入 目标 的 类 型 匹配 。 如 果 没 有 指定 injection-target， 那 么 需要 指定 env- 
entry-type ° 


FIGURE 14-15 env-entry Element Structure 


21.ejb-ref 元 素 


ejb-ref 声 明了 一 个 对 企业 bean 的 home 引 用 。ejb-ref-name 指 定 了 引用 企业 bean 的 部 署 组 件 代 
码 中 使 用 的 名 称 。ejb-ref-type 是 引用 的 企业 bean 期 望 的 类 型 ， 它 可 以 是 Entity 或 Session。 
home 定 义 了 引用 的 企业 bean 的 home 接 口 的 完全 限定 名 称 。remote 定 义 了 引用 的 企业 bean 的 
remote 接 口 的 完全 限定 名 称 。ejb-link 指 定 了 连接 到 企业 bean 的 一 个 EJB 引 用 。 更 多 详细 信息 
请 参阅 Java 平 台 企 业 版 第 6 版 。 除 了 这 些 元 素 之 外 ，injection-target 元 素 可 以 用 于 定义 指定 的 
企业 bean 注 入 到 一 个 组 件 的 字段 或 属性 。 


FIGURE 14-16 ejb-ref Element Structure 


22.ejb-local-ref 元 素 


ejb-local-ref 声 明了 对 企业 bean 的 本 地 home 引 用 。local-home 定 义 了 企业 bean 的 本 地 home 接 
口 的 完全 限定 名 称 。local 定 义 了 企业 bean 的 本 地 接口 的 完全 限定 名 称 。 


FIGURE 14-17 ejb-local-ref Element Structure 


23.service-ref 元 素 


service-ref 声 明了 一 个 对 Web service 的 引用 。service-ref-name 声 明了 用 于 查找 Web service 
模块 组 件 的 逻辑 名 称 。 建 议 所 有 service 的 引用 名 称 以 /service/ 开头 。service-interface 定 义 了 
客户 端 依赖 的 JAX-WS Service 接 口 的 完全 限定 类 名 称 。 在 大 多 数 情况 下 ， 这 个 值 是 
javax.xml.rpc.Service。 也 可 以 指定 一 个 JAX-WS 生 成 的 服务 接口 类 。 wsdl-file 元 素 包 含 了 
WSDL 文 件 的 URI 位 置 。 这 个 位 置 相 对 于 模块 根 目 录 。jaxrpc-mapping-file 包 含 了 描述 应 用 程 
序 使 用 的 Java 接 口 和 wsdl-file 中 的 WSDL 描 述 之 间 的 JAX-WS 了 映射 的 文件 名 。 这 个 文件 名 是 一 


个 模块 文件 中 的 相对 路 径 。service-qname 元 素 声明 了 具体 的 被 称 为 NSDL 的 服务 元 素 。 如 果 
没有 声明 wsdl-file， 则 不 需要 指定 。port-component-ref 元 素 声明 了 一 个 在 容器 中 解析 服务 终 
端 接口 到 一 个 WSDL 端 口 的 客户 端 依 赖 关系 。 它 使 用 一 个 特别 的 端口 组 件 选择 性 地 关联 服务 终 
端 接口 。 这 仅 被 容器 用 于 Service.getPort(Class) 方 法 调用 。handler 元 素 为 端口 组 件 声明 处 理 
法 。 处 理 程序 可 以 使 用 Handlerlnfo 接 口 访问 init-param 名 值 对 。 如 果 未 指定 port-name， 处 理 
器 将 与 service 的 所 有 端口 关联 。 详 细 信 息 请 参阅 JSR-109 规 范 
[http://www.jcp.org/en/jsr/detail?id=109] ° 7# TJava EE 实现 的 容器 不 要 求 支持 这 个 元 素 。 


Sey, 


SA 


S 
KJ 


FIGURE 14-18 service-ref Element Structure 


24 .resource-ref7L & 


resource-ref 元 素 包 含 了 部 署 组 件 对 外 部 资源 的 引用 声明 。res-ref-name 指 定 了 一 个 资源 管理 
器 连接 工厂 引用 的 名 称 。 这 个 名 称 是 一 个 相对 于 java:com /env 上 下 文 的 JNDI 名 称 。 在 部 署 文 
件 中 这 个 名 称 必 须 是 唯一 的 。res-type 元 素 指 定数 据 源 的 类 型 。 该 类 型 是 一 个 希望 由 数据 源 实 
现 的 Java 语 言 类 或 接口 的 完全 限定 名 。res-auth 指 定 部 署 组 件 代 码 是 否 以 编程 方式 注册 到 资源 
管理 器 ， 或 容器 是 否 将 代表 的 部 署 组 件 注册 到 资源 管理 器 。 如 果 是 第 二 种 情况 ， 容 器 使 用 部 
署 器 提供 的 信息 。res-sharing-scope 指 定 了 通过 给 定 的 资源 管理 器 连接 工厂 引用 获取 的 连接 
是 否 可 以 共享 。 如 果 指 定 了 这 个 值 ， 它 必须 是 Shareable 或 Unshareable。 可 选 的 injection- 
target 元 素 用 于 定义 把 指定 的 资源 注入 到 字段 或 JavaBean 属 性 。 


FIGURE 14-19 resource-ref Element Structure 


25.resource-env-ref 元 素 


resource-env-ref 包含 了 部 署 组 件 和 对 部 署 组 件 环 境 中 的 资源 有 关 的 管理 对 象 的 引用 。 
resource-env-ref-name 指 定 了 资源 环境 引用 的 名 称 。 它 的 值 是 部 署 组 件 代码 中 使 用 的 环境 入 
口 名 称 ， 它 是 一 个 相对 于 java:comp/env 上 下 文 的 JNDI 名 称 ， 并 且 在 部 署 组 件 中 必须 是 唯一 
的 。resource-env-ref-type 指 定 了 资源 环境 引用 的 类 型 。 它 是 一 个 Java 语 言 类 或 接口 的 完全 限 
定名 。 可 选 的 injection-target 元 素 用 于 定义 把 指定 的 资源 注入 到 字段 或 JavaBean 必 性。 必须 
提供 resource-env-ref-type 除 非 指 定 了 注入 目标 ， 在 这 种 情况 下 ， 将 使 用 目标 的 类 型 。 如 果 两 
者 都 指定 ， 该 类 型 必须 与 注入 目标 的 类 型 兼容 。 


FIGURE 14-20 resource-env-ref Element Structure 


26.message-destination-ref 元 素 


message-destination-ref 元 素 包 含 了 部 署 组 件 和 对 部 署 组 件 环 境 中 的 资源 有 关 的 消息 目标 的 
引用 声明 。message-destination-ref-name 元 素 指 定 了 一 个 消息 目标 引用 的 名 称 ， 它 的 值 是 部 
署 组 件 代 码 中 使 用 的 环境 入 口 名 称 。 这 个 名 称 是 一 个 相对 于 java:comp/env 上 下 文 的 JNDI 名 
称 ， 并 且 在 企业 bean 的 ejb-jar 中 或 其 他 部 署 文件 中 必须 是 唯一 的 。message-destination-type 


指定 了 目标 的 类 型 。 这 个 类 型 由 希望 目标 实现 的 Java 接 口 指定 。message-destination-usage 
指定 了 引用 表示 的 消息 目标 的 用 法 。 这 个 值 表示 是 使 用 目标 信息 中 的 消息 ， 还 是 产生 目标 消 
息 ， 亦 或 两 者 兼 而 有 之 。 汇 编 器 将 使 用 此 信息 来 连接 目标 的 生产 者 与 消费 者 。message- 
destination-link 把 一 个 消息 目标 引用 或 消息 驱动 bean 连 接 到 一 个 消息 目标 。 汇 编 器 设置 这 个 值 
来 反映 应 用 程序 中 的 生产 者 和 消费 者 消息 流 。 这 个 值 必 须 是 同一 个 部 署 文件 或 同一 个 Java 
EE 应 用 程序 单元 的 另 一 个 部 署 文件 中 的 消息 目标 的 message-destination-name。 或 者 ， 这 个 
值 可 以 由 一 个 路 径 名 称 组 成 ， 使 用 目标 添加 的 message-destination-name 和 通过 "#" 分 隔 路 径 
名 称 说 明 一 个 部 署 文 件 包含 引用 的 消息 目标 。 这 个 路 径 名 称 是 相对 于 部 署 文件 ， 包 含 引用 消 
息 目 标的 部 署 组 件 。 这 允许 多 个 消息 目标 使 用 相同 的 名 称 作 为 唯一 标识 。 可 选 的 injection- 
target 元 素 用 于 定义 把 指定 的 资源 注入 到 字段 或 JavaBean 属 性 。 必 须 指定 message- 
destination-type 除非 注入 目标 已 经 指定 ， 在 这 种 情况 下 ， 将 使 用 目标 的 类 型 。 如 果 两 者 都 指 
定 ， 该 类 型 必须 与 注入 目标 的 类 型 兼容 。 


示例 : 


<message-destination-ref> 
<message-destination-ref-name> 
jms/StockQueue 
</message-destination-ref -name> 
<message-destination-type> 
javax.jms.Queue 
</message-destination-type> 
<message -destination-usage> 
Consumes 
</message-destination-usage> 
<message-destination-link> 
CorporateStocks 
</message-destination-link> 
</message-destination-ref> 


FIGURE 14-21 message-destination-ref Element Structure 


27.message-destination 1. #- 


message-destination 指 定 消息 的 目标 。 这 个 元 素 所 描述 的 逻辑 目标 由 部 署 器 映射 到 物理 目 
标 。message-destination-name 元 素 指 定 了 消息 目标 的 名 称 。 该 名 称 在 部 署 文件 的 消息 目标 
名 称 中 必须 是 唯一 的 。 示例 : 


CorporateStocks </message-destination-name> </message-destination> 


FIGURE 14-22 message-destination Element Structure 


28.locale-encoding-mapping-list 元 素 


locale-encoding-mapping-list 包 含 了 语言 环境 和 编码 之 间 的 映射 。 由 子 元 素 locale-encoding- 
mapping 指 定 。 


示例 : 


<locale-encoding-mapping-list> 
<locale-encoding-mapping> 
<locale>ja</locale> 
<encoding>Shift_JIS</encoding> 
</locale-encoding-mapping> 
</locale-encoding-mapping-list> 


FIGURE 14-23 locale-encoding-mapping-list Element Structure 


示例 
下 面 的 例子 说 明了 部 署 描述 文件 模式 中 列 出 的 定义 的 用 法 。 


一 个 简单 的 例子 


CODE EXAMPLE 14-1 Basic Deployment Descriptor Example 


<?xml version="1.0" encoding="IS0-8859-1"?> 
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd" 
version="2.5"> 
<display-name>A Simple Application</display -name> 
<context -param> 
<param-name>Webmaster</param-name> 
<param-value>webmaster@mycorp.com</param-value> 
</context -param> 
<servlet> 
<servlet -name>catalog</servlet -name> 
<servlet-class>com.mycorp.CatalogServlet 
</servlet-class> 
<init-param> 
<param-name>catalog</param-name> 
<param-value>Spring</param-value> 
</init -param> 
</servlet> 
<servlet -mapping> 
<servlet-name>catalog</servlet-name> 
<url-pattern>/catalog/*</url-pattern> 
</servlet -mapping> 
<session-config> 
<session-timeout>30</session-timeout> 
</session-config> 
<mime -mapping> 
<extension>pdf</extension> 
<mime-type>application/pdf</mime-type> 
</mime -mapping> 
<welcome-file-list> 
<welcome-file>index.jsp</welcome- file> 
<welcome-file>index.html</welcome- file> 
<welcome-file>index.htm</welcome- file> 
</welcome-file-list> 
<error-page> 
<error-code>404</error-code> 
<location>/404.html</location> 
</error-page> 
</web-app> 


安全 的 例子 


CODE EXAMPLE 14-2 Deployment Descriptor Example Using Security 


<?xml version="1.0" encoding="IS0-8859-1"?> 
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd" 
version="2.5"> 
<display-name>A Secure Application</display-name> 
<servlet> 
<servlet-name>catalog</servlet-name> 
<servlet-class>com.mycorp.CatalogServlet 
</servlet-class> 
<init-param> 
<param-name>catalog</param-name> 
<param-value>Spring</param-value> 
</init-param> 
<security-role-ref> 
<role-name>MGR</role-name> 
<!-- role name used in code --> 
<role-link>manager</role-link> 
</security-role-ref> 
</servlet> 
<security-role> 
<role-name>manager</role-name> 
</security-role> 
<servlet -mapping> 
<servlet-name>catalog</servlet-name> 
<url-pattern>/catalog/*</url-pattern> 
</servlet -mapping> 
<security-constraint> 
<web-resource-collection> 
<web-resource-name>SalesInfo 
</web-resource-name> 
<url-pattern>/salesinfo/*</url-pattern> 
<http-method>GET</http-method> 
<http-method>POST</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>manager</role-name> 
</auth-constraint> 
<user-data-constraint> 
<transport -guarantee>CONFIDENTIAL 
</transport-guarantee> 
</user -data-constraint> 
</security-constraint> 
</web -app> 


与 其 它 规范 有 关 的 要 求 


本 章 列 出 对 web 容器 的 要 求 ， 它 已 经 包含 在 容器 产品 中 了 ， 还 包括 其 他 Java 技术 。 


下 面 章节 中 任何 涉及 到 Java EE 应 用 的 profile， 不 只 是 完整 的 Java EE profile， 还 包括 任何 
支持 Servelt 的 profile， 像 Java EE Web Profile。 有 关 配 置 文件 的 更 多 信息 ， 请 参阅 Java 
EE 平台 规范 。 


会 话 


分 布 式 的 servlet 容器 必须 支持 Java EE 实现 机 制 所 必需 的 其 他 Java EE 对 象 从 一 个 JVM £ 


移 到 另 一 个 。 


Web 应 用 


Web 应 用 Class Loader 


Servlet 容器 是 一 个 Java EE 产品 的 一 部 分 ， 不 应 该 允许 应 用 程序 重 写 Java SE 或 Java EE 
平台 的 类 ， 比 如 那些 在 Java. 和 javax. 命名 空间 中 的 类 ，Java SE 或 Java EE 不 允许 被 修 
改 。 


Web 应 用 程序 环境 


Java EE 定义 了 一 个 命名 的 环境 ， 允 许 应 用 程序 在 没有 明确 的 知道 外 部 信息 是 如 何 命名 和 组 
织 的 情况 下 轻松 地 访问 资源 和 外 部 信息 。 


由 于 servlet 是 Java EE 技术 的 一 个 完整 的 组 件 类 型 ， 已 经 在 Web 应 用 程序 部 署 文件 中 规定 了 
允许 servlet 获取 引用 资源 和 企业 bean 的 指定 信息 。 此 包含 信息 的 的 部 署 元 素 有 : 


e env-entry 

e ejb-ref 

e ejb-local-ref 

e resource-ref 

e resource-env-ref 

e service-ref 

e message-destination-ref 
e persistence-context-ref 
e persistence-unit-ref 


开发 人 员 使 用 这 些 元 素来 描述 在 Web 容器 中 运行 时 Web 应 用 程序 需要 在 JNDI 命 名 空间 中 注 
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Java EE 规范 第 5 章 中 描述 了 关于 Java EE 环境 设置 的 要 求 Servlet 容器 属于 Java EE 技术 标准 
实现 的 一 部 分 ， 它 必须 支持 这 种 语法 。 查 阅 Java EE 规范 可 获取 更 多 详细 信息 。 这 种 类 型 的 
servlet 容器 必须 支持 查找 这 种 对 象 并 在 受 servlet 容器 管理 的 线程 上 执行 时 调用 这 些 对 象 。 当 
在 开发 人 员 创 建 的 线程 上 执行 时 ， 这 种 类 型 的 servlet 容器 应 该 支持 这 种 行为 ， 但 目前 没有 要 
求 这 样 做 。 这 样 的 规定 将 被 添加 到 本 规范 的 下 一 个 版 本 中 。 开 发 人 员 应 该 小 心 ， 不 推荐 应 用 
程序 创建 的 线程 依赖 这 种 能 力 ， 因 为 它 是 不 可 移植 的 。 


Web 模 块 上 下 文 根 URL 的 JNDI 名 称 


Java EE 平 台 规 范 定义 了 一 个 标准 化 的 全 局 JNDI 命 名 空间 和 一 系列 相关 的 命名 空间 映射 到 不 
同 的 Java EE 应 用 程序 范围 。 应 用 程序 可 以 使 用 这 些 命名 空间 可 移植 地 检索 组 件 和 资源 的 引 
用 。 本 节 定 义 的 Web 应 用 程序 的 基本 URL 是 需要 注册 的 JNDI 名 称 。 


为 一 个 Web 应 用 程序 上 下 文 根 目 录 预 定义 的 java.net.URL 资 源 的 名 称 的 语法 如 下 : 


全 局 命名 空间 中 


java:global[/<app-name>]/<module-name>!ROOT 


， 应 用 程序 指定 的 命名 空间 中 


java:app/<module-name>!ROoT 


确定 应 用 程序 名 称 和 模块 名 称 的 规则 请 参阅 Java EE 规 范 8.1.1 节 (组 件 创建 ) 和 8.1.2 节 (应 
用 程序 组 装 ) 。 


只 有 当 Web 应 用 打包 成 一 个 .ear 文 件 时 才 适 合 使 用 <app-name> ° 


java:app 前 组 允许 一 个 组 件 内 执行 的 Java EE 应 用 程序 来 访问 特定 于 应 用 程序 的 命名 空间 。 
java:app 名 称 允许 一 个 企业 应 用 程序 中 的 模块 引用 同一 个 企业 应 用 程序 中 其 他 模块 的 上 下 文 根 
目录 。 <module-name> 是 java:app url 语 法 的 必要 组 成 部 分 。 


示例 


然后 ， 可 以 在 应 用 程序 使 用 上 述 的 URL， 如 下 : 


如 果 Web 应 用 程序 使 用 模块 名 称 myVWebApp 独 立 部 署 。URL 可 被 注入 到 另 一 个 web 模 块 ， 如 
TI: 


CODE EXAMPLE 15-1 


QResource(lookup=“java:global/myWebApp!RO00T") 
URL myWebApp; 


当 打 包 到 一 个 名 为 myApp 的 EAR 文 件 中 时 ， 可 像 下 面 这 样 使 用 : 
CODE EXAMPLE 15-2 


@Resource(lookup=“java: global/myApp/myWebApp ! ROOT” ) 
URL myWebApp; 


Web 应 用 


196 


安全 


本 节 详 细 介 绍 了 Web 容 器 包含 Gm 品 中 时 额外 的 安全 性 要 求 ， 包含 EJB ` + JACC He 
(3) JASPIC 。 以 下 各 节 将 介绍 这 些 要 求 。 


EJBTM 调 用 传播 的 安全 标识 


必须 始终 提供 一 个 安全 标识 或 主体 (principal)， 用 于 调用 一 个 企业 bean。 从 Web 应 用 程序 中 
调用 企业 Bean 的 默认 模式 是 为 把 Web 用 户 的 安全 标识 传播 到 EJB 容器 。 在 其 他 情况 下 ， 
Web 容器 必须 允许 不 了 解 Web 容器 或 EJB 容器 的 web 用户 进 IRAR: 


* Web 容器 必须 支持 未 把 自己 授权 给 容器 的 用 户 访 问 Web 资源 。 这 是 在 互联 网 上 访问 
Web 资 源 常见 的 模式 。 
e. 应 用 程序 代码 可 以 是 单 点 登录 和 基于 调用 者 标识 的 定制 化 数据 的 唯一 处 理 器 。 


在 这 些 情况 下 ，Web 应 用 程序 部 署 描述 文件 可 以 指定 一 个 run-as 元 素 。 当 为 Servlet 指定 了 一 
个 run-as 角色 时 ，Servlet 容器 必须 传播 主要 的 映射 到 该 角色 ， 作 为 任何 从 Servlet 到 EJB 调 
用 的 安全 标识 ， 包 括 从 Servlet 的 init 和 destory 方 法 进行 原始 调用 。 安 全 角色 名 必须 ar 
用 程序 定义 的 安全 角色 名 称 之 一 。 由 于 Web 容 器 作为 Java EE 平台 的 一 部 分 运行 ， 在 同一 
Java EE 应 用 程序 中 调用 EJB 组 件 ， 以 及 调用 部 署 在 其 他 Java EE 中 的 应 用 程序 都 必须 支持 
run-as 元 素 的 使 用 。 


容器 授权 的 要 求 


在 Java EE 产品 中 或 包括 支持 Java 容器 授权 合约 (JAAC, i.e, JSR 115) 的 产品 中 ， 所 有 
Servlet 容器 必须 实现 支持 JACC。JACC 规 范 可 在 此 处 下 载 http://www.jcp.org/en/jsr/detail? 


在 Java EE 产品 中 或 包括 支持 Java 容器 认证 SPI| (JASPIC, i.e, JSR 196) 的 产品 中 ， 所 有 
Servlet 容器 必须 实现 JASPIC 规范 的 Servlet 容器 Profile。JASPIC 规范 可 在 此 处 下 载 
http://www.jcp.org/en/jsr/detail?id=196 


部 署 


本 节 详 细 说 明了 部 署 描述 符 , 打 包 和 部 署 描 述 符 处 理 Java EE 技术 兼容 的 容器 和 产品 的 要 求 , 包 
括 对 JSP 和 Web 服务 的 支持 。 


部 署 描述 符 元 素 


以 下 附加 元 素 存在 于 Web 应 用 程序 部 署 描述 符 ， 用 于 满足 Web 容 — 页 面 的 要 求 ， 
或 作为 Java EE 应 用 服务 器 的 一 部 分 o 它们 不 需要 由 希望 多 仅 支 持 Servlet 规范 容 ge 器 支持 : 


e jsp-config 

e 用 于 描述 资源 引用 的 语法 (env-entry, ejb-ref, ejb-local-ref, resource-ref, resource-env- 
ref) 

o 指定 消息 目的 地 的 语法 (message-destination, message-destination-ref) 

引用 Web Service (service-ref) 

。 引用 持久 化 上 下 文 (persistence-context-ref) 

引用 持久 化 单元 (persistence-unit-ref) 


这 些 元 素 的 语法 现在 由 Java 服 务 器 页 面 (JavaServer Pages) 规范 2.2 版 本 ， 和 Java EE 规 
范 控 制 。 


包 和 JAX-WS 组 件 部 署 


Web 容器 可 以 选择 支持 运行 实现 JAX-PRC 和 /或 JAX-WS 规范 定义 的 Web 服 务 端 点 
(endpoint) 编写 的 组 件 。 需 要 Web 容 器 衣 入 一 个 Java EE 符合 的 实现 来 支持 JAX-RPC 和 
JAX-WS Web Service 组 件 。 本 节 描 述 了 Web 容 器 包括 也 支持 JAX-RPC 和 JAX-WS 的 产品 的 打 
包 和 部 署 模型 。JSR-109 [http://jcp.org/jsr/detail/109.jsp] 定 义 了 用 于 打包 Web service 接 口 与 
它 关 联 的 WSDL 描 述 和 关联 的 类 的 模型 。 它 定义 了 一 种 机 制 用 于 启用 了 JAX-WS 和 JAX-RPC 
的 容器 链接 到 一 个 实现 了 这 个 Web service 的 组 件 。 一 个 JAX-WS 或 JAX-RPC Web service 实 
现 组 件 使 用 JAX-WS 和 /或 JAX-RPC 规 范 定义 的 APl， 其 定义 了 它 与 启用 了 JAX-WS 和 /或 JAX- 
RPC 的 Web 容 器 之 间 的 契约 。 它 被 打包 到 WAR 文 件 。VWeb service 开 发 人 员 使 用 平常 
的 <servlet> 声明 来 声明 这 个 组 件 。 局 用 了 JAX-WS 和 JAX-RPC 的 Web 容 器 必须 支持 开发 人 
员 在 使 用 的 Web 部 署 描述 符 中 定义 用 于 端点 实现 组 件 的 如 下 信息 ， 使 用 与 HTTP Servlet 组 件 
使 用 的 Servlet 元 素 相 同 的 语法 。 子 元 素 用 于 以 如 下 方式 指定 端点 信息 | 


e Servlet-name 元 素 定义 可 用 于 找 出 WAR 中 的 处 于 其 他 组 件 中 的 这 个 端点 描述 的 逻辑 名 字 
e servlet-class 元 素 提 供 这 个 端点 实现 的 全 限定 Java 类 名 

e description 元 素 可 以 用 于 描述 该 组 件 ， 并 可 能 显示 在 一 个 工具 中 

load-on-startup 元 素 指定 Web 容 器 中 的 人 人 对 于 其 它 组 件 的 初始 化 顺序 

e security-role-ref 元 素 可 以 用 于 测试 是 否 已 通过 身份 认证 的 用 户 在 一 个 逻辑 安全 角色 中 
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由 开发 人 员 定 义 的 用 于 这 个 组 件 的 任何 Servlet 初 始 化 参数 可 能 被 容器 忽略 。 此 外 ， 启 用 了 
JAX-WS 和 JAX-RPC 的 Web 组 件 继承 了 用 于 定义 如 下 信息 的 传统 Web 组 件 机 制 : 


e 使 用 Servlet 映 射 技术 映射 组 件 到 Web 容 器 的 URL 命 名 空间 

. 使 用 安全 约束 在 Web 组 件 上 授权 约束 

e 能 够 使 用 servlet 过 滤器 提供 底层 (low-level) 字 节 流 支持 ， 用 于 使 用 过 滤器 映射 技术 操纵 
JAX-WS 和 /或 JAX-RPC 消 息 

o 任何 与 组 件 关联 的 HTTP 会 话 的 超时 特性 

e 链接 到 存储 在 JNDO 命 名 空间 的 Java EER Z 所 有 上 述 要 求 可 使 用 定义 在 8.2 节 的 “可 插 拔 
性 ?的 播 拔 机 制 得 到 满足 。 


处 理 部 署 描述 符 的 规则 


符合 Java EE 技术 实现 一 部 分 的 容器 和 工具 ， 需 要 根据 XML schema 验证 部 署 描 述 符 结构 的 
正确 性 。 建 议 验 证 ， 但 对 于 不 符合 Java EE 技术 实现 的 web 容 器 和 工具 不 是 必须 的 。 


注解 和 资源 注入 


Java 元 数据 (Metadata) 规范 (JSR-175) ， 是 J2SE 5.0 和 更 高 版 本 的 一 部 分 ， 提 供 一 种 在 
Java 代 码 中 指定 配置 数据 的 方法 。Java 代 码 中 的 元 数据 也 被 称 为 注解 。 在 JavaEE 中 ， 注 解 用 
于 声明 对 外 部 资源 的 依赖 和 在 Java 代 码 中 的 配置 数据 而 无 需 在 配置 文件 中 定义 该 数据 。 


本 节 描 述 了 在 Java EE 技术 兼容 的 Servlet 容 器 中 注解 和 资源 注入 的 行为 。 本 节 扩 展 了 Java EE 
规范 第 5 节 标 题 为 “资源 ， 命 名 和 注入 ”。 


注解 必须 支持 以 下 容器 管理 的 类 ， 其 实现 了 以 下 接口 并 在 web 应 用 部 署 描述 符 中 声明 ， 或 使 用 
定义 在 8.1 节 “注解 和 可 播 拔 性 ”的 注解 声明 或 编程 式 添 加 的 。 


TABLE 15-1 Components and Interfaces supporting Annotations and Dependency Injection 


组 件 类 型 实现 下 面 接口 的 类 
Servlets javax.servlet.Servlet 
Filters javax.servlet.Filter 


javax.servlet.ServletContextListener 
javax.servlet.ServletContextAttributeListener 
javax.servlet.ServletRequestListener 

Listeners javax.serviet.ServietRequestAttributeListener 
javax.servlet.http.HttpSessionListener 
javax.servlet.http.HttpSessionAttributeListener 
javax.servlet.http.HttpSessionidListener javax.servlet.AsyncListener 


Web 容器 不 需要 为 存在 注解 的 除了 上 表 15-1 列 出 的 那些 类 执行 资源 注入 。 
引用 必须 在 任何 生命 周期 方法 调用 之 前 注入 ， 且 组 件 实例 对 应 用 是 可 用 的 。 


在 一 个 web 应 用 中 ， 使 用 资源 注入 的 类 只 有 当 它 们 位 于 WEB-INF/classes 目 录 ， 或 如 果 它 们 被 
打包 到 位 于 WEB-INF 目 录 下 的 jar 文 件 中 ， 它 们 的 注解 将 被 处 理 。 容 器 可 以 选择 性 地 为 在 其 他 
地 方 的 应 用 类 路 径 中 找到 的 类 处 理 资源 注入 注解 。 


Web 应 用 部 署 描述 符 的 web-app 元 素 上 包含 一 个 metadata-complete 属 性 。metadata- 
complete 属 性 定义 了 web.xml 描 述 符 是 否 是 完整 的 ， 或 是 否 应 考虑 部 署 过 程 中 使 用 的 其 他 资源 
的 元 数据 。 元 数据 可 能 来 自 web.xml 文 件 、web-fragment.xml 文 件 、WEB-INF/classes 中 的 类 
文件 上 的 注解 、 和 WEB-INF/lib 目 录 中 的 jar 文 件 中 的 文件 上 的 注解 。 如 果 metadata-complete 
设置 为 “true”， 部 署 工具 仅 检 查 Wweb.xml 文 件 且 必须 忽略 如 出 现在 应 用 的 类 文件 上 的 
@WebServlet、@WebFilter、 和 @WebListener 注 解 ， 且 必须 也 忽略 WEB-INF/lib 中 的 打包 在 
jar 文 件 的 任何 web-fragment.xml 描 述 符 。 如 果 metadata-complete 没 有 指定 或 设置 为 false”， 
部 署 工具 必须 检查 类 文件 和 web-fragment.xml 文 件 的 元 数据 ， 就 像 前 面 指定 的 那样 。 


web-fragment.xml 的 web-fragment 元 素 也 包含 了 metadata-complete 属 性 。 该 属性 定义 了 对 于 
给 定 片段 的 web-fragment.xml 描 述 符 是 否 是 完整 的 ， 或 者 是 否 应 该 扫描 相关 的 jar 文 件 中 的 类 
中 的 注解 。 如 果 metadata-complete 设 置 为 “true”， 部 署 工具 仅 检 查 web-fragment.xml 文 件 且 必 
须 急 略 如 出 现在 fragment 的 类 文件 上 的 @WebServlet、@WebFilter、 和 人 @WebListener 注 

解 。 如 果 metadata-complete 没 有 指定 或 设置 为 "false"， 部 署 工 具 必 须 检 查 类 文件 的 元 数据 。 


以 下 是 Java EE 技术 兼容 的 web 容器 需要 的 注解 。 


@DeclareRoles 


该 注解 用 于 定义 由 应 用 安全 模型 组 成 的 安全 角色 。 该 注解 指定 在 类 上 ， 且 它 用 于 定义 能 从 注 
解 的 类 的 方法 内 测试 ( 即 ， 通 过 调用 isUserlnRole) 的 角色 。 由 于 用 在 @RolesAllowed 而 隐 
式 声明 的 角色 ， 不 必 使 用 @DeclareRoles 注解 明确 声明 。@DeclareRoles 注解 仅 可 以 定义 在 
实现 了 javax.servlet.Servlet 接口 或 它 的 一 个 子 类 的 类 中 。 


以 下 是 如 果 使 用 该 注解 的 一 个 例子 。 


CODE EXAMPLE 15-3 @DeclareRoles Annotation Example 


@DeclareRoles("BusinessAdmin" ) 
public class CalculatorServlet ( 
Eh ict 


} 


声明 @DeclareRoles("BusinessAdmin") 等 价 于 如 下 在 web.xml 中 的 定义 。 


CODE EXAMPLE 15-4 @DeclareRoles web.xml 


<web -app> 
<security-role> 
<role-name>BusinessAdmin</role-name> 
</security-role> 
</web -app> 


该 注解 不 是 用 于 重新 链接 (relink) 应 用 角色 到 其 他 角色 。 当 这 样 的 链接 是 必需 的 ， 它 是 通过 
在 相关 的 部 署 描述 符 中 定义 一 个 适当 的 security-role-ref 来 实现 。 


当 从 注解 的 类 调用 isUserlnRole 时 ， 与 调用 的 类 关联 的 调用 者 身份 以 相同 名 称 作 为 
isCallerInRole 的 参数 来 测试 角色 成 员 身份 。 如 果 已 经 定义 了 参数 role-name 的 一 个 security- 
role-ref， 调 用 者 测试 映射 到 role-name 的 角色 成 员 身份 。 


为 进一步 了 解 @DeclareRoles 注 解 细 节 ， 请 参考 Java™ 平 台 ™M 的 通用 注解 (Common 
Annotation) 规范 ((JSR 250) 第 2.12 节 。 


@EJB 


企业 级 JavaBean™ 3.2 (EJB) 组 件 可 以 从 一 个 web 组 件 使 用 @EJB 注解 引用 。@EJB 注 解 
提供 了 与 部 署 描述 符 中 声明 ejb-ref 或 ejb-local-ref 元 素 等 价 的 功能 。 有 一 个 相应 的 @EJB 注 
解 的 字段 被 注入 一 个 相应 的 EJB 组 件 的 引用 。 


一 个 例子 : 


@EJB private ShoppingCart myCart; 
在 上 述 情 况 下 ， 到 EJB 组 件 “myCart" 的 一 个 引用 被 注入 作为 私有 字段 myCart" 的 值 ， 在 声明 
注入 的 类 可 用 之 前 。 


进一步 了 解 @EJB 注 解 的 行为 请 参考 EJB 3.2 规 范 (JSR 345) 第 11.5.1 节 > 


@EJBs 
@EJBs 注解 允许 在 单个 资源 上 声明 多 于 一 个 @EJB 注解 。 
一 个 例子 : 


CODE EXAMPLE 15-5 @EJBs Annotation Example 


@EJBs({@EJB(Calculator), @EJB(ShoppingCart)}) 
public class ShoppingCartServlet { 
VIERE: 


} 


上 面 例子 中 的 EJB 224 ShoppingCart 和 Calculator *tShoppingCartServlet 是 可 用 的 。 
ShoppingCartServlet 仍然 必须 使 用 INDI 查找 引用 ， 但 不 需要 声明 在 web.xml 文件 中 。 


@Resource 


@Resource 注解 用 于 声明 到 资源 的 引用 ， 如 一 个 数据 源 (data source) 、Java 消 息 服 务 

(JMS) 目的 地 、 或 环境 项 (environment entry) 。 该 注解 等 价 于 在 部 署 描述 符 中 声明 
resource-ref、message-destination-ref、 或 env-ref、 或 resource-env-ref 元 素 。 @Resource 
注解 指定 在 一 个 类 、 方 法 或 字段 上 。 容 器 负责 注入 到 由 @Resource 注解 声明 的 资源 的 引用 和 
映射 到 适当 的 JNDI 资 源 。 请 参考 Java EE 规范 第 5 章 进 一 步 了 解 细节 。 


以 下 是 一 个 @Resource 注 解 的 例子 : 


CODE EXAMPLE 15-6 @Resource Example 


@Resource 

private javax.sql.DataSource catalogDS; 

public getProductsByCategory() { 
// get a connection and execute the query 
Connection conn = catalogDS.getConnection(); 


在 上 面 的 示例 代码 中 ，servlet 、filter 或 listener 声 明 一 个 javax.sql.DataSource 类 型 的 
catalogDS 字段 ， 在 该 组 件 对 应 用 可 用 之 前 由 容器 注入 数据 源 引 用 。 数 据 源 JNDI 映 射 是 从 字 
段 名 "catalogDS" 和 类 型 (javax.sql.DataSource ) 推导 出 来 的 。 此 外 ，catalogDS 数 据 源 不 再 
需要 定义 在 部 署 描述 符 中 。 

进一步 了 解 @Resource 注 解 的 语义 请 参考 Java™ 平 台 ™M 的 通用 注解 规范 (JSR 250) 第 2.3 节 


和 Java EE 7 规范 第 5.2.5 节 。 


@PersistenceContext 


该 注解 指定 容器 管理 的 用 于 引用 持久 化 单元 (persistence unit) 的 实体 管理 器 (entity 
manager) ° 


一 个 例子 


CODE EXAMPLE 15-7 @PersistenceContext Example 


@PersistenceContext (type=EXTENDED) 
EntityManager em; 


进一步 了 解 @PersistenceContext 注 解 的 行为 请 参考 Java 持 久 化 API (Java Persistence API) 
2.1 版 本 第 10.5.1 节 (JSR 338) 。 


@PersistenceContexts 


PersistenceContexts 注解 允许 在 一 个 资源 上 声明 多 于 一 个 @PersistenceContext。 进 一 步 了 
解 @PersistenceContexts 注解 的 行为 请 参考 Java 持 久 化 API〈Java Persistence API) 2.1 版 
本 第 10.5.1 节 (JSR 338) 。 


@PersistenceUnit 


@PersistenceUnit 注解 提供 声明 在 servlet 中 的 到 企业 级 JavaBean 组 件 实体 管理 器 工厂 
(entity manager factory) 的 引用 。 实 体 管理 器 工厂 绑 定 到 一 个 单独 的 persistence.xml 配置 
文件 ， 该 文件 在 EJB 3.2 规 范 (JSR 345) 中 11.10 节 中 描述 。 


一 个 示例 : 


CODE EXAMPLE 15-8 @PersistenceUnit Example 


@PersistenceUnit 
EntityManagerFactory emf; 


进一步 了 解 @ PersistenceUnit 注 解 的 行为 请 参考 Java 持 久 化 API (Java Persistence API) 2.1 
版 本 第 10.5.2 节 (JSR 338) 。 


@PersistenceUnits 


该 注解 允许 在 一 个 资源 上 声明 多 于 一 个 @PersistentUnit。 进 一 步 了 解 @ PersistentUnits 注解 
的 行为 请 参考 Java 持 久 化 API (Java Persistence API) 2.1 版 本 第 10.5.2 节 (JSR 338) 。 


@PostConstruct 


@PostConstruct 注解 声明 在 一 个 无 参 的 方法 上 ， 且 必须 不 抛 出 任何 检查 的 异常 。 返 回 值 必 须 
是 void。 该 方法 必须 在 资源 注入 完成 之 后 被 调用 且 在 组 件 的 任何 生命 周期 方法 之 前 被 调用 。 


示例 


CODE EXAMPLE 15-9 @PostConstruct Example 


@PostConstruct 
public void postConstruct() { 


} 
上 面 的 示例 展示 了 一 个 使 用 @PostConstruct 注解 的 方法 。@PostConstruct 注解 必须 支持 那 


些 支持 依赖 注入 的 所 有 类 并 即使 该 类 不 要 求 任何 资源 注入 也 会 被 调用 。 如 果 该 方法 抛 出 未 受 
查 一 次 ， 该 类 必须 不 被 放 入 服务 中 且 该 实例 没有 方法 被 调用 。 


参考 Java EE 规范 第 2.5 节 和 Java™ 平 台 ™M 的 通用 注解 规范 的 第 2.5 节 获取 更 多 细节 。 


@PreDestroy 
@PreDestroy 注解 声明 在 容器 管理 组 件 的 一 个 方法 上 。 该 方法 在 容器 移 除 该 组 件 之 前 调用 。 
一 个 例子 : 


CODE EXAMPLE 15-10 @PreDestroy Example 


@PreDestroy 
public void cleanup() { 
// clean up any open resources 


} 


使 用 @PreDestroy 注 解 的 该 方法 必须 返回 void 且 必 须 不 抛 出 受 查 异 常 。 该 方法 可 以 是 public、 
protected、package 私 有 或 private。 该 方法 必须 不 是 Static 的 ， 但 它 可 以 是 final 的 。 


参考 JSR 250 第 2.6 节 获取 更 多 细节 。 


@Resources 


由 于 Java 元 数据 规范 不 允许 在 相同 的 注解 目标 以 相同 名 字 使 用 多 个 注解 ， 因 此 @Resources 注 
解 充当 容器 的 多 个 @Resource 注 解 。 


一 个 例子 : 


CODE EXAMPLE 15-11 @Resources Example 


@Resources ({ 
@Resource(name="myDB” type=javax.sql.DataSource), 
@Resource(name="myMQ” type=javax.jms.ConnectionFactory) 


1) 
public class CalculatorServlet ( 
Walon 


} 
在 上 面 的 示例 中 CalculatorServlet 通过 @Resources 注解 使 的 IMS 连接 工厂 和 数据 源 变 得 
可 用 。 


@Resources 注解 的 语义 是 进一步 详细 的 常见 的 注释 的 Java™M 平 台 ™M 规 范 (JSR 250)2.4 节 


@RunAs 


@RunAs 注解 等 价 于 部 署 描述 符 中 的 run-as 注 解 。@RunAs 注 解 可 能 仅 定义 在 
javax.servlet.Servlet 接口 或 它 的 子 类 的 类 实现 上 。 


一 个 例子 : 


CODE EXAMPLE 15-12 @RunAs Example 


@RunAs( “Admin” ) 
public class CalculatorServlet ( 


QEJB private ShoppingCart myCart; 


public void doGet(HttpServletRequest, req, HttpServletResponse res) { 


故人 本 本 
myCart.getTotal(); 
UL a 
} 

} 
A/ 

} 


@RunAs(“Admin’) 语句 等 价 于 : 


CODE EXAMPLE 15-13 @RunAs web.xml Example 


<servlet> 
<servlet-name>CalculatorServlet</servlet-name> 
<run-as>Admin</run-as> 

</servlet> 


以 上 示例 展示 了 当 调 用 myCart.getTotal() 方法 时 Servlet 如 何 使 用 @RunAs 注解 来 传播 安全 
身份 “Admin" 到 EJB 组 件 。 进 一 步 了 解 传播 身份 的 细节 请 看 第 15.3.1 节 “EJB™ 调 用 的 安全 身份 
传播 ”。 


进一步 了 解 @RunAs 注 解 的 细节 请 参考 Java™M 平 台 ™M 的 通用 注解 规范 (JSR 250) 第 2.7 节 。 


@WebServiceRef 


@WebServiceRef 注解 在 一 个 web 组 件 中 使 用 可 能 在 部 署 描述 符 中 的 resource-ref 相同 的 方式 
提供 一 个 到 web service 的 引用 。 


A er 
QWebServiceRef private MyService service; 
在 这 个 例子 中 ， 一 个 到 web service“MyService" 的 引用 将 被 注入 到 声明 该 注解 的 类 。 


@WebServiceRefs 


这 个 注解 允许 在 单个 资源 上 声明 多 于 一 个 的 @WebServiceRef 注解 。 进 一 步 了 解 这 个 注解 的 
行为 请 参考 JAX-WS 规 范 (JSR 224) 第 7 章节 。 


JavaEE 要 求 的 上 下 文 和 依赖 注入 


在 一 个 支持 JavaEE (CDI) 上 下 文 和 依赖 注入 且 CDI 开 启 的 产品 中 ， 实 现 必 须 支持 使 用 CDI 
managed bean 。Servlet、Filter、Listener 和 HttpUpgradeHandler 必 须 支持 CDI 注 入 和 描述 在 
EE.5.24 节 的 拦截 器 使 用 ，JavaEE 7 平台 规范 “支持 依赖 注入 ”。 


